From 0dbbb1cb3f6ed2983105620bc49191e3b0436f37 Mon Sep 17 00:00:00 2001 From: Toshiki Sonoda Date: Fri, 12 Aug 2022 09:22:53 +0900 Subject: Add restart --cidfile, --filter --cidfile : Read container ID from the specified file and restart the container. --filter : restart the filtered container. Signed-off-by: Toshiki Sonoda --- docs/source/markdown/podman-restart.1.md | 38 ++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs') diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md index 323087069..b9da413f7 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -14,14 +14,46 @@ Containers will be stopped if they are running and then restarted. Stopped containers will not be stopped and will only be started. ## OPTIONS + #### **--all**, **-a** + Restart all containers regardless of their current state. +#### **--cidfile** + +Read container ID from the specified file and restart the container. Can be specified multiple times. + +#### **--filter**, **-f**=*filter* + +Filter what containers restart. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + #### **--latest**, **-l** + Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) #### **--running** + Restart all containers that are already in the *running* state. #### **--time**, **-t**=*seconds* @@ -59,6 +91,12 @@ Restart all containers $ podman restart --all ``` +Restart container using ID specified in a given files. +``` +$ podman restart --cidfile /home/user/cidfile-1 +$ podman restart --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + ## SEE ALSO **[podman(1)](podman.1.md)** -- cgit v1.2.3-54-g00ecf From 056917c223f054bd0b4526fce0800258a410cd68 Mon Sep 17 00:00:00 2001 From: Дилян Палаузов Date: Sat, 13 Aug 2022 12:15:40 +0300 Subject: Reword --exit-policy option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Insisting on “DCO” imposes formalities, that serve self-purpose. One cannot assume that the submitter has time or will to read texts about symbolism in software contributions. If the system wants to see the text nrEAUIEUAIe eanuitdnuae EAIUEAUIAIE »ℓ§444.3.72b)°»°ℓ§euaieauuae in each commit, people will write this, or any other text, that the system wants to see. All such text, which presence is mandated by the system, has the same value. Signed-off-by: Дилян Палаузов --- RELEASE_NOTES.md | 2 +- docs/source/markdown/podman-pod-create.1.md.in | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index b762bbbe3..8a9672507 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -11,7 +11,7 @@ - The `podman play kube` command now supports volumes with the `BlockDevice` and `CharDevice` types ([#13951](https://github.com/containers/podman/issues/13951)). - The `podman play kube` command now features a new flag, `--userns`, to set the user namespace of created pods. Two values are allowed at present: `host` and `auto` ([#7504](https://github.com/containers/podman/issues/7504)). - The `podman play kube` command now supports setting the type of created init containers via the `io.podman.annotations.init.container.type` annotation. -- Pods now have include an exit policy (configurable via the `--exit-policy` option to `podman pod create`), which determines what will happen to the pod's infra container when the entire pod stops. The default, `continue`, acts as Podman currently does, while a new option, `stop`, stops the infra container after the last container in the pod stops, and is used by default for pods from `podman play kube` ([#13464](https://github.com/containers/podman/issues/13464)). +- The `podman pod create` command now supports an exit policy (configurable via the `--exit-policy` option), which determines what will happen to the pod's infra container when the entire pod stops. The default, `continue`, acts as Podman currently does, while a new option, `stop`, stops the infra container after the last container in the pod stops. The latter is used for pods created via `podman play kube` ([#13464](https://github.com/containers/podman/issues/13464)). - The `podman pod create` command now allows the pod's name to be specified as an argument, instead of using the `--name` option - for example, `podman pod create mypod` instead of the prior `podman pod create --name mypod`. Please note that the `--name` option is not deprecated and will continue to work. - The `podman pod create` command's `--share` option now supports adding namespaces to the set by prefacing them with `+` (as opposed to specifying all namespaces that should be shared) ([#13422](https://github.com/containers/podman/issues/13422)). - The `podman pod create` command has a new option, `--shm-size`, to specify the size of the `/dev/shm` mount that will be shared if the pod shares its UTS namespace ([#14609](https://github.com/containers/podman/issues/14609)). diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 73b634548..c12f296b4 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -89,10 +89,10 @@ Set custom DNS search domains in the /etc/resolv.conf file that will be shared b Set the exit policy of the pod when the last container exits. Supported policies are: -| Exit Policy | Description | -| ------------------ | --------------------------------------------------------------------------- | -| *continue* | The pod continues running when the last container exits. Used by default. | -| *stop* | The pod is stopped when the last container exits. Used in `kube play`. | +| Exit Policy | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | +| *continue* | The pod continues running, by keeping its infra container alive, when the last container exits. Used by default. | +| *stop* | The pod (including its infra container) is stopped when the last container exits. Used in `kube play`. | #### **--gidmap**=*container_gid:host_gid:amount* -- cgit v1.2.3-54-g00ecf 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') 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 From 7e7a79b075f7d65657d95169f02c2c1c03198b93 Mon Sep 17 00:00:00 2001 From: Nalin Dahyabhai Date: Tue, 16 Aug 2022 18:30:19 -0400 Subject: podman manifest create: accept --amend and --insecure flags Accept a --amend flag in `podman manifest create`, and treat `--insecure` as we would `--tls-verify=false` in `podman manifest`'s "add", "create", and "push" subcommands. Signed-off-by: Nalin Dahyabhai --- cmd/podman/manifest/add.go | 12 ++++++++- cmd/podman/manifest/create.go | 32 ++++++++++++++++++++++-- cmd/podman/manifest/push.go | 15 ++++++++--- docs/source/markdown/podman-manifest-create.1.md | 12 +++++++++ pkg/api/handlers/libpod/manifests.go | 3 ++- pkg/api/server/register_manifest.go | 4 +++ pkg/bindings/manifests/types.go | 3 ++- pkg/bindings/manifests/types_create_options.go | 15 +++++++++++ pkg/domain/entities/manifest.go | 5 ++++ pkg/domain/infra/abi/manifest.go | 10 +++++++- pkg/domain/infra/tunnel/manifest.go | 2 +- test/e2e/manifest_test.go | 8 ++++++ 12 files changed, 111 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/cmd/podman/manifest/add.go b/cmd/podman/manifest/add.go index 35583ffcb..09a1a9a36 100644 --- a/cmd/podman/manifest/add.go +++ b/cmd/podman/manifest/add.go @@ -2,6 +2,7 @@ package manifest import ( "context" + "errors" "fmt" "github.com/containers/common/pkg/auth" @@ -20,6 +21,7 @@ type manifestAddOptsWrapper struct { entities.ManifestAddOptions TLSVerifyCLI bool // CLI only + Insecure bool // CLI only CredentialsCLI string } @@ -77,6 +79,8 @@ func init() { flags.StringVar(&manifestAddOpts.OSVersion, osVersionFlagName, "", "override the OS `version` of the specified image") _ = addCmd.RegisterFlagCompletionFunc(osVersionFlagName, completion.AutocompleteNone) + flags.BoolVar(&manifestAddOpts.Insecure, "insecure", false, "neither require HTTPS nor verify certificates when accessing the registry") + _ = flags.MarkHidden("insecure") flags.BoolVar(&manifestAddOpts.TLSVerifyCLI, "tls-verify", true, "require HTTPS and verify certificates when accessing the registry") variantFlagName := "variant" @@ -89,7 +93,7 @@ func init() { } func add(cmd *cobra.Command, args []string) error { - if err := auth.CheckAuthFile(manifestPushOpts.Authfile); err != nil { + if err := auth.CheckAuthFile(manifestAddOpts.Authfile); err != nil { return err } @@ -109,6 +113,12 @@ func add(cmd *cobra.Command, args []string) error { if cmd.Flags().Changed("tls-verify") { manifestAddOpts.SkipTLSVerify = types.NewOptionalBool(!manifestAddOpts.TLSVerifyCLI) } + if cmd.Flags().Changed("insecure") { + if manifestAddOpts.SkipTLSVerify != types.OptionalBoolUndefined { + return errors.New("--insecure may not be used with --tls-verify") + } + manifestAddOpts.SkipTLSVerify = types.NewOptionalBool(manifestAddOpts.Insecure) + } listID, err := registry.ImageEngine().ManifestAdd(context.Background(), args[0], args[1:], manifestAddOpts.ManifestAddOptions) if err != nil { diff --git a/cmd/podman/manifest/create.go b/cmd/podman/manifest/create.go index 435b4a57c..0a0ea1d88 100644 --- a/cmd/podman/manifest/create.go +++ b/cmd/podman/manifest/create.go @@ -1,16 +1,26 @@ package manifest import ( + "errors" "fmt" + "github.com/containers/image/v5/types" "github.com/containers/podman/v4/cmd/podman/common" "github.com/containers/podman/v4/cmd/podman/registry" "github.com/containers/podman/v4/pkg/domain/entities" "github.com/spf13/cobra" ) +// manifestCreateOptsWrapper wraps entities.ManifestCreateOptions and prevents leaking +// CLI-only fields into the API types. +type manifestCreateOptsWrapper struct { + entities.ManifestCreateOptions + + TLSVerifyCLI, Insecure bool // CLI only +} + var ( - manifestCreateOpts = entities.ManifestCreateOptions{} + manifestCreateOpts = manifestCreateOptsWrapper{} createCmd = &cobra.Command{ Use: "create [options] LIST [IMAGE...]", Short: "Create manifest list or image index", @@ -32,10 +42,28 @@ func init() { }) flags := createCmd.Flags() flags.BoolVar(&manifestCreateOpts.All, "all", false, "add all of the lists' images if the images to add are lists") + flags.BoolVar(&manifestCreateOpts.Amend, "amend", false, "modify an existing list if one with the desired name already exists") + flags.BoolVar(&manifestCreateOpts.Insecure, "insecure", false, "neither require HTTPS nor verify certificates when accessing the registry") + _ = flags.MarkHidden("insecure") + flags.BoolVar(&manifestCreateOpts.TLSVerifyCLI, "tls-verify", true, "require HTTPS and verify certificates when accessing the registry") } func create(cmd *cobra.Command, args []string) error { - imageID, err := registry.ImageEngine().ManifestCreate(registry.Context(), args[0], args[1:], manifestCreateOpts) + // TLS verification in c/image is controlled via a `types.OptionalBool` + // which allows for distinguishing among set-true, set-false, unspecified + // which is important to implement a sane way of dealing with defaults of + // boolean CLI flags. + if cmd.Flags().Changed("tls-verify") { + manifestCreateOpts.SkipTLSVerify = types.NewOptionalBool(!manifestCreateOpts.TLSVerifyCLI) + } + if cmd.Flags().Changed("insecure") { + if manifestCreateOpts.SkipTLSVerify != types.OptionalBoolUndefined { + return errors.New("--insecure may not be used with --tls-verify") + } + manifestCreateOpts.SkipTLSVerify = types.NewOptionalBool(manifestCreateOpts.Insecure) + } + + imageID, err := registry.ImageEngine().ManifestCreate(registry.Context(), args[0], args[1:], manifestCreateOpts.ManifestCreateOptions) if err != nil { return err } diff --git a/cmd/podman/manifest/push.go b/cmd/podman/manifest/push.go index 756ed2a74..fd67769b8 100644 --- a/cmd/podman/manifest/push.go +++ b/cmd/podman/manifest/push.go @@ -1,6 +1,7 @@ package manifest import ( + "errors" "fmt" "io/ioutil" @@ -20,9 +21,9 @@ import ( type manifestPushOptsWrapper struct { entities.ImagePushOptions - TLSVerifyCLI bool // CLI only - CredentialsCLI string - SignPassphraseFileCLI string + TLSVerifyCLI, Insecure bool // CLI only + CredentialsCLI string + SignPassphraseFileCLI string } var ( @@ -82,6 +83,8 @@ func init() { _ = pushCmd.RegisterFlagCompletionFunc(signPassphraseFileFlagName, completion.AutocompleteDefault) flags.BoolVar(&manifestPushOpts.TLSVerifyCLI, "tls-verify", true, "require HTTPS and verify certificates when accessing the registry") + flags.BoolVar(&manifestPushOpts.Insecure, "insecure", false, "neither require HTTPS nor verify certificates when accessing the registry") + _ = flags.MarkHidden("insecure") flags.BoolVarP(&manifestPushOpts.Quiet, "quiet", "q", false, "don't output progress information when pushing lists") flags.SetNormalizeFunc(utils.AliasFlags) @@ -130,6 +133,12 @@ func push(cmd *cobra.Command, args []string) error { if cmd.Flags().Changed("tls-verify") { manifestPushOpts.SkipTLSVerify = types.NewOptionalBool(!manifestPushOpts.TLSVerifyCLI) } + if cmd.Flags().Changed("insecure") { + if manifestPushOpts.SkipTLSVerify != types.OptionalBoolUndefined { + return errors.New("--insecure may not be used with --tls-verify") + } + manifestPushOpts.SkipTLSVerify = types.NewOptionalBool(manifestPushOpts.Insecure) + } digest, err := registry.ImageEngine().ManifestPush(registry.Context(), args[0], args[1], manifestPushOpts.ImagePushOptions) if err != nil { return err diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md index 77a4b9db6..f2aac6069 100644 --- a/docs/source/markdown/podman-manifest-create.1.md +++ b/docs/source/markdown/podman-manifest-create.1.md @@ -22,11 +22,23 @@ If any of the images which should be added to the new list or index are themselves lists or indexes, add all of their contents. By default, only one image from such a list will be added to the newly-created list or index. +#### **--amend** + +If a manifest list named *listnameorindexname* already exists, modify the +preexisting list instead of exiting with an error. The contents of +*listnameorindexname* are not modified if no *imagename*s are given. + +#### **--tls-verify** + +Require HTTPS and verify certificates when talking to container registries. (defaults to true) + ## EXAMPLES ``` podman manifest create mylist:v1.11 9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f +podman manifest create --amend mylist:v1.11 +9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f ``` ``` diff --git a/pkg/api/handlers/libpod/manifests.go b/pkg/api/handlers/libpod/manifests.go index b0c93f3b9..fa83bbfe1 100644 --- a/pkg/api/handlers/libpod/manifests.go +++ b/pkg/api/handlers/libpod/manifests.go @@ -36,6 +36,7 @@ func ManifestCreate(w http.ResponseWriter, r *http.Request) { Name string `schema:"name"` Images []string `schema:"images"` All bool `schema:"all"` + Amend bool `schema:"amend"` }{ // Add defaults here once needed. } @@ -70,7 +71,7 @@ func ManifestCreate(w http.ResponseWriter, r *http.Request) { imageEngine := abi.ImageEngine{Libpod: runtime} - createOptions := entities.ManifestCreateOptions{All: query.All} + createOptions := entities.ManifestCreateOptions{All: query.All, Amend: query.Amend} manID, err := imageEngine.ManifestCreate(r.Context(), query.Name, query.Images, createOptions) if err != nil { utils.InternalServerError(w, err) diff --git a/pkg/api/server/register_manifest.go b/pkg/api/server/register_manifest.go index c22479cf9..7a55eaefe 100644 --- a/pkg/api/server/register_manifest.go +++ b/pkg/api/server/register_manifest.go @@ -117,6 +117,10 @@ func (s *APIServer) registerManifestHandlers(r *mux.Router) error { // name: all // type: boolean // description: add all contents if given list + // - in: query + // name: amend + // type: boolean + // description: modify an existing list if one with the desired name already exists // - in: body // name: options // description: options for new manifest diff --git a/pkg/bindings/manifests/types.go b/pkg/bindings/manifests/types.go index e23ef798d..5f2557fe1 100644 --- a/pkg/bindings/manifests/types.go +++ b/pkg/bindings/manifests/types.go @@ -8,7 +8,8 @@ type InspectOptions struct { //go:generate go run ../generator/generator.go CreateOptions // CreateOptions are optional options for creating manifests type CreateOptions struct { - All *bool + All *bool + Amend *bool } //go:generate go run ../generator/generator.go ExistsOptions diff --git a/pkg/bindings/manifests/types_create_options.go b/pkg/bindings/manifests/types_create_options.go index 960332a82..09942c00a 100644 --- a/pkg/bindings/manifests/types_create_options.go +++ b/pkg/bindings/manifests/types_create_options.go @@ -31,3 +31,18 @@ func (o *CreateOptions) GetAll() bool { } return *o.All } + +// WithAmend set field Amend to given value +func (o *CreateOptions) WithAmend(value bool) *CreateOptions { + o.Amend = &value + return o +} + +// GetAmend returns value of field Amend +func (o *CreateOptions) GetAmend() bool { + if o.Amend == nil { + var z bool + return z + } + return *o.Amend +} diff --git a/pkg/domain/entities/manifest.go b/pkg/domain/entities/manifest.go index 126b76c62..f17079271 100644 --- a/pkg/domain/entities/manifest.go +++ b/pkg/domain/entities/manifest.go @@ -4,7 +4,12 @@ import "github.com/containers/image/v5/types" // ManifestCreateOptions provides model for creating manifest type ManifestCreateOptions struct { + // True when adding lists to include all images All bool `schema:"all"` + // Amend an extant list if there's already one with the desired name + Amend bool `schema:"amend"` + // Should TLS registry certificate be verified? + SkipTLSVerify types.OptionalBool `json:"-" schema:"-"` } // ManifestAddOptions provides model for adding digests to manifest list diff --git a/pkg/domain/infra/abi/manifest.go b/pkg/domain/infra/abi/manifest.go index e0c11267e..7e8c86526 100644 --- a/pkg/domain/infra/abi/manifest.go +++ b/pkg/domain/infra/abi/manifest.go @@ -32,7 +32,15 @@ func (ir *ImageEngine) ManifestCreate(ctx context.Context, name string, images [ manifestList, err := ir.Libpod.LibimageRuntime().CreateManifestList(name) if err != nil { - return "", err + if errors.Is(err, storage.ErrDuplicateName) && opts.Amend { + amendList, amendErr := ir.Libpod.LibimageRuntime().LookupManifestList(name) + if amendErr != nil { + return "", err + } + manifestList = amendList + } else { + return "", err + } } addOptions := &libimage.ManifestListAddOptions{All: opts.All} diff --git a/pkg/domain/infra/tunnel/manifest.go b/pkg/domain/infra/tunnel/manifest.go index 2a514861d..2e6134051 100644 --- a/pkg/domain/infra/tunnel/manifest.go +++ b/pkg/domain/infra/tunnel/manifest.go @@ -15,7 +15,7 @@ import ( // ManifestCreate implements manifest create via ImageEngine func (ir *ImageEngine) ManifestCreate(ctx context.Context, name string, images []string, opts entities.ManifestCreateOptions) (string, error) { - options := new(manifests.CreateOptions).WithAll(opts.All) + options := new(manifests.CreateOptions).WithAll(opts.All).WithAmend(opts.Amend) imageID, err := manifests.Create(ir.ClientCtx, name, images, options) if err != nil { return imageID, fmt.Errorf("error creating manifest: %w", err) diff --git a/test/e2e/manifest_test.go b/test/e2e/manifest_test.go index ee954a1a4..145a016ea 100644 --- a/test/e2e/manifest_test.go +++ b/test/e2e/manifest_test.go @@ -49,6 +49,14 @@ var _ = Describe("Podman manifest", func() { session := podmanTest.Podman([]string{"manifest", "create", "foo"}) session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) + + session = podmanTest.Podman([]string{"manifest", "create", "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).To(ExitWithError()) + + session = podmanTest.Podman([]string{"manifest", "create", "--amend", "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) }) It("create w/ image", func() { -- cgit v1.2.3-54-g00ecf From d50ff4f512856907982e1ebb92d60fc7980f730e Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Wed, 17 Aug 2022 12:44:42 -0400 Subject: Add podman secret create -d as alias for --driver for Docker compatibility Signed-off-by: Daniel J Walsh --- cmd/podman/secrets/create.go | 2 +- docs/source/markdown/podman-secret-create.1.md | 2 +- test/e2e/secret_test.go | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/cmd/podman/secrets/create.go b/cmd/podman/secrets/create.go index 8ecfecf69..01775f563 100644 --- a/cmd/podman/secrets/create.go +++ b/cmd/podman/secrets/create.go @@ -46,7 +46,7 @@ func init() { cfg := registry.PodmanConfig() - flags.StringVar(&createOpts.Driver, driverFlagName, cfg.Secrets.Driver, "Specify secret driver") + flags.StringVarP(&createOpts.Driver, driverFlagName, "d", cfg.Secrets.Driver, "Specify secret driver") flags.StringToStringVar(&createOpts.DriverOpts, optsFlagName, cfg.Secrets.Opts, "Specify driver specific options") _ = createCmd.RegisterFlagCompletionFunc(driverFlagName, completion.AutocompleteNone) _ = createCmd.RegisterFlagCompletionFunc(optsFlagName, completion.AutocompleteNone) diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index e08afb388..39e0c6843 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -20,7 +20,7 @@ Secrets will not be committed to an image with `podman commit`, and will not be ## OPTIONS -#### **--driver**=*driver* +#### **--driver**, **-d**=*driver* Specify the secret driver (default **file**, which is unencrypted). diff --git a/test/e2e/secret_test.go b/test/e2e/secret_test.go index ed328d84a..f557aaaa0 100644 --- a/test/e2e/secret_test.go +++ b/test/e2e/secret_test.go @@ -40,7 +40,7 @@ var _ = Describe("Podman secret", func() { err := ioutil.WriteFile(secretFilePath, []byte("mysecret"), 0755) Expect(err).To(BeNil()) - session := podmanTest.Podman([]string{"secret", "create", "--driver-opts", "opt1=val", "a", secretFilePath}) + session := podmanTest.Podman([]string{"secret", "create", "-d", "file", "--driver-opts", "opt1=val", "a", secretFilePath}) session.WaitWithDefaultTimeout() secrID := session.OutputToString() Expect(session).Should(Exit(0)) -- cgit v1.2.3-54-g00ecf From f6e7b0b59d365f42cae70702f53f87d534d4c2f6 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Wed, 17 Aug 2022 12:49:30 -0400 Subject: Add podman secret inspect -f alias for --format: Docker compatibility Signed-off-by: Daniel J Walsh --- cmd/podman/secrets/inspect.go | 2 +- docs/source/markdown/podman-secret-inspect.1.md | 2 +- test/e2e/secret_test.go | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/cmd/podman/secrets/inspect.go b/cmd/podman/secrets/inspect.go index 1fcc676b4..c99e555ba 100644 --- a/cmd/podman/secrets/inspect.go +++ b/cmd/podman/secrets/inspect.go @@ -34,7 +34,7 @@ func init() { }) flags := inspectCmd.Flags() formatFlagName := "format" - flags.StringVar(&format, formatFlagName, "", "Format volume output using Go template") + flags.StringVarP(&format, formatFlagName, "f", "", "Format volume output using Go template") _ = inspectCmd.RegisterFlagCompletionFunc(formatFlagName, common.AutocompleteFormat(&entities.SecretInfoReport{})) } diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md index df16ba6fa..1a7115f63 100644 --- a/docs/source/markdown/podman-secret-inspect.1.md +++ b/docs/source/markdown/podman-secret-inspect.1.md @@ -15,7 +15,7 @@ Secrets can be queried individually by providing their full name or a unique par ## OPTIONS -#### **--format**=*format* +#### **--format**, **-f**=*format* Format secret output using Go template. diff --git a/test/e2e/secret_test.go b/test/e2e/secret_test.go index f557aaaa0..3410c0af5 100644 --- a/test/e2e/secret_test.go +++ b/test/e2e/secret_test.go @@ -49,7 +49,7 @@ var _ = Describe("Podman secret", func() { inspect.WaitWithDefaultTimeout() Expect(inspect).Should(Exit(0)) Expect(inspect.OutputToString()).To(Equal(secrID)) - inspect = podmanTest.Podman([]string{"secret", "inspect", "--format", "{{.Spec.Driver.Options}}", secrID}) + inspect = podmanTest.Podman([]string{"secret", "inspect", "-f", "{{.Spec.Driver.Options}}", secrID}) inspect.WaitWithDefaultTimeout() Expect(inspect).Should(Exit(0)) Expect(inspect.OutputToString()).To(ContainSubstring("opt1:val")) -- cgit v1.2.3-54-g00ecf From 546bb3548ce9af58ebf0a627eb66ea7ad2163c6b Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Wed, 17 Aug 2022 13:14:46 -0400 Subject: Add podman stats --no-trunc option This is for compatibility with Docker. Partial fix for https://github.com/containers/podman/issues/14917 Signed-off-by: Daniel J Walsh --- cmd/podman/containers/stats.go | 5 +++++ docs/source/markdown/podman-stats.1.md | 10 ++++++++++ test/e2e/stats_test.go | 3 ++- 3 files changed, 17 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/cmd/podman/containers/stats.go b/cmd/podman/containers/stats.go index 0dd8ce80a..f29bbf34c 100644 --- a/cmd/podman/containers/stats.go +++ b/cmd/podman/containers/stats.go @@ -58,6 +58,7 @@ type statsOptionsCLI struct { var ( statsOptions statsOptionsCLI + notrunc bool ) func statFlags(cmd *cobra.Command) { @@ -69,6 +70,7 @@ func statFlags(cmd *cobra.Command) { flags.StringVar(&statsOptions.Format, formatFlagName, "", "Pretty-print container statistics to JSON or using a Go template") _ = cmd.RegisterFlagCompletionFunc(formatFlagName, common.AutocompleteFormat(&containerStats{})) + flags.BoolVar(¬runc, "no-trunc", false, "Do not truncate output") flags.BoolVar(&statsOptions.NoReset, "no-reset", false, "Disable resetting the screen between intervals") flags.BoolVar(&statsOptions.NoStream, "no-stream", false, "Disable streaming stats and only pull the first result, default setting is false") intervalFlagName := "interval" @@ -186,6 +188,9 @@ type containerStats struct { } func (s *containerStats) ID() string { + if notrunc { + return s.ContainerID + } return s.ContainerID[0:12] } diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index d87da6a60..8d07be1a0 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -61,6 +61,10 @@ Do not clear the terminal/screen in between reporting intervals Disable streaming stats and only pull the first result, default setting is false +#### **--no-trunc** + +Do not truncate output + ## EXAMPLE ``` @@ -76,6 +80,12 @@ ID NAME CPU % MEM USAGE / LIMIT MEM % NET IO BL a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- / -- 2 ``` +``` +$ podman stats --no-trunc 3667 --format 'table {{ .ID }} {{ .MemUsage }}' +ID MEM USAGE / LIMIT +3667c6aacb06aac2eaffce914c01736420023d56ef9b0f4cfe58b6d6a78b7503 49.15kB / 67.17GB +``` + ``` # podman stats --no-stream --format=json a9f80 [ diff --git a/test/e2e/stats_test.go b/test/e2e/stats_test.go index 3000a819f..981c00316 100644 --- a/test/e2e/stats_test.go +++ b/test/e2e/stats_test.go @@ -79,9 +79,10 @@ var _ = Describe("Podman stats", func() { session := podmanTest.RunTopContainer("") session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) - session = podmanTest.Podman([]string{"stats", "--all", "--no-stream", "--format", "\"{{.ID}}\""}) + session = podmanTest.Podman([]string{"stats", "--all", "--no-trunc", "--no-stream", "--format", "\"{{.ID}}\""}) session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) + Expect(len(session.OutputToStringArray()[0])).Should(BeEquivalentTo(66)) }) It("podman stats with GO template", func() { -- cgit v1.2.3-54-g00ecf From 0dd2fcf715ec8a3ae8e15212289e5320e7cded19 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Wed, 17 Aug 2022 12:30:51 -0400 Subject: Add podman manifest create -a. Alias for --amend:Docker compatibility Signed-off-by: Daniel J Walsh --- cmd/podman/manifest/create.go | 2 +- docs/source/markdown/podman-manifest-create.1.md | 2 +- test/e2e/manifest_test.go | 28 ++++++++++++++---------- 3 files changed, 19 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/cmd/podman/manifest/create.go b/cmd/podman/manifest/create.go index 0a0ea1d88..2ea40d832 100644 --- a/cmd/podman/manifest/create.go +++ b/cmd/podman/manifest/create.go @@ -42,7 +42,7 @@ func init() { }) flags := createCmd.Flags() flags.BoolVar(&manifestCreateOpts.All, "all", false, "add all of the lists' images if the images to add are lists") - flags.BoolVar(&manifestCreateOpts.Amend, "amend", false, "modify an existing list if one with the desired name already exists") + flags.BoolVarP(&manifestCreateOpts.Amend, "amend", "a", false, "modify an existing list if one with the desired name already exists") flags.BoolVar(&manifestCreateOpts.Insecure, "insecure", false, "neither require HTTPS nor verify certificates when accessing the registry") _ = flags.MarkHidden("insecure") flags.BoolVar(&manifestCreateOpts.TLSVerifyCLI, "tls-verify", true, "require HTTPS and verify certificates when accessing the registry") diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md index f2aac6069..06a24da2b 100644 --- a/docs/source/markdown/podman-manifest-create.1.md +++ b/docs/source/markdown/podman-manifest-create.1.md @@ -22,7 +22,7 @@ If any of the images which should be added to the new list or index are themselves lists or indexes, add all of their contents. By default, only one image from such a list will be added to the newly-created list or index. -#### **--amend** +#### **--amend**, **-a** If a manifest list named *listnameorindexname* already exists, modify the preexisting list instead of exiting with an error. The contents of diff --git a/test/e2e/manifest_test.go b/test/e2e/manifest_test.go index 145a016ea..1c4aad710 100644 --- a/test/e2e/manifest_test.go +++ b/test/e2e/manifest_test.go @@ -46,17 +46,23 @@ var _ = Describe("Podman manifest", func() { processTestResult(f) }) It("create w/o image", func() { - session := podmanTest.Podman([]string{"manifest", "create", "foo"}) - session.WaitWithDefaultTimeout() - Expect(session).Should(Exit(0)) - - session = podmanTest.Podman([]string{"manifest", "create", "foo"}) - session.WaitWithDefaultTimeout() - Expect(session).To(ExitWithError()) - - session = podmanTest.Podman([]string{"manifest", "create", "--amend", "foo"}) - session.WaitWithDefaultTimeout() - Expect(session).Should(Exit(0)) + for _, amend := range []string{"--amend", "-a"} { + session := podmanTest.Podman([]string{"manifest", "create", "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + + session = podmanTest.Podman([]string{"manifest", "create", "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).To(ExitWithError()) + + session = podmanTest.Podman([]string{"manifest", "create", amend, "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + + session = podmanTest.Podman([]string{"manifest", "rm", "foo"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + } }) It("create w/ image", func() { -- cgit v1.2.3-54-g00ecf From a0560eefaa1a5777ac910ec26af7a690a4b1f653 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 16 Aug 2022 09:36:02 -0600 Subject: Man pages: refactor common options: cert-dir ...and, tweak markdown-process-review so it can detect and remove identical files, making review easier. Signed-off-by: Ed Santiago --- docs/source/markdown/options/cert-dir.md | 5 +++ docs/source/markdown/podman-build.1.md.in | 5 +-- docs/source/markdown/podman-kube-play.1.md.in | 5 +-- docs/source/markdown/podman-pull.1.md.in | 5 +-- hack/markdown-preprocess-review | 56 ++++++++++++++++++++++++++- 5 files changed, 62 insertions(+), 14 deletions(-) create mode 100644 docs/source/markdown/options/cert-dir.md (limited to 'docs') diff --git a/docs/source/markdown/options/cert-dir.md b/docs/source/markdown/options/cert-dir.md new file mode 100644 index 000000000..4d05075cf --- /dev/null +++ b/docs/source/markdown/options/cert-dir.md @@ -0,0 +1,5 @@ +#### **--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)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** for details. +(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index b49beb3bf..c29cf997d 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -164,10 +164,7 @@ If a capability is specified to both the **--cap-add** and **--cap-drop** options, it will be dropped, regardless of the order in which the options were given. -#### **--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) +@@option cert-dir @@option cgroup-parent diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 83b9f9904..14c5f2498 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -118,10 +118,7 @@ and as a result environment variable `FOO` will be set to `bar` for container `c Build images even if they are found in the local storage. Use `--build=false` to completely disable builds. (This option is not available with the remote Podman client) -#### **--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) +@@option cert-dir #### **--configmap**=*path* diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index cf06cc6a8..46eaa706a 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -53,10 +53,7 @@ All tagged images in the repository will be pulled. @@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)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +@@option cert-dir #### **--creds**=*[username[:password]]* diff --git a/hack/markdown-preprocess-review b/hack/markdown-preprocess-review index a487265ad..a3e237fb6 100755 --- a/hack/markdown-preprocess-review +++ b/hack/markdown-preprocess-review @@ -114,8 +114,60 @@ for my $i (0..$#all_opts) { next if $ans =~ /^n/i; exit 0 if $ans =~ /^q/i; - system("diffuse", "-w", glob("*")) == 0 - or die "Diffuse failed\n"; + # Try to cull the files (remove identical ones) + my @files = glob("*"); + my $winner = pop @files; + + for my $f (@files) { + system('cmp', '-s', $f, $winner); + if ($? == 0) { + print "[ $f is the one we went with; removing from list ]\n"; + unlink $f; + next; + } + + system('wdiff', '-1', '-2', '-3', $f, $winner); + if ($? == 0) { + print "[ $f is whitespace-identical with what we went with ]\n"; + unlink $f; + next; + } + } + + # Recompute @files, in case some were deleted above + @files = glob("*"); pop @files; + + for (my $i=0; $i < $#files; $i++) { + my $f1 = $files[$i]; + next unless -e $f1; + + for (my $j=$i+1; $j <= $#files; $j++) { + my $f2 = $files[$j]; + next unless -e $f2; + + system('wdiff', '-1', '-2', '-3', $f1, $f2); + if ($? == 0) { + print "[ $f2 : removing, it =~ $f1 ]\n"; + unlink $f2; + } + } + } + + # Recompute @files, in case some were deleted above + @files = glob("*"); + + # diffuse works great for 3-4 files, passable for 5, not at all for >5 + if (@files <= 5) { + system("diffuse", "-w", @files) == 0 + or die "Diffuse failed\n"; + } + else { + # Too many files. Go by threes. + my $winner = pop @files; + for (my $i=0; $i < @files; $i += 3) { + system("diffuse", "-w", @files[$i..$i+2], $winner); + } + } } -- cgit v1.2.3-54-g00ecf From f8e73eadd2a6792dc941902b2854949c044a511b Mon Sep 17 00:00:00 2001 From: Toshiki Sonoda Date: Mon, 22 Aug 2022 17:45:31 +0900 Subject: [CI:DOCS] Update how to enable resource limit delegation Add a information about `cpu-shares` option and `CPUSET` limits. Signed-off-by: Toshiki Sonoda --- docs/source/markdown/options/cpu-period.md | 4 ++-- docs/source/markdown/options/cpu-quota.md | 4 ++-- docs/source/markdown/options/cpu-shares.md | 4 ++++ docs/source/markdown/options/cpuset-cpus.md | 4 ++++ docs/source/markdown/options/cpuset-mems.md | 4 ++++ troubleshooting.md | 33 +++++++++++++++++------------ 6 files changed, 35 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md index 8df6445e9..efbe6c2ab 100644 --- a/docs/source/markdown/options/cpu-period.md +++ b/docs/source/markdown/options/cpu-period.md @@ -5,6 +5,6 @@ duration in microseconds. Once the container's CPU quota is used up, it will not be scheduled to run until the current period ends. Defaults to 100000 microseconds. -On some systems, changing the CPU limits may not be allowed for non-root +On some systems, changing the resource limits may not be allowed for non-root users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpu-quota.md b/docs/source/markdown/options/cpu-quota.md index 67b9dee8c..753797bad 100644 --- a/docs/source/markdown/options/cpu-quota.md +++ b/docs/source/markdown/options/cpu-quota.md @@ -7,6 +7,6 @@ CPU resource. The limit is a number in microseconds. If a number is provided, the container will be allowed to use that much CPU time until the CPU period ends (controllable via **--cpu-period**). -On some systems, changing the CPU limits may not be allowed for non-root +On some systems, changing the resource limits may not be allowed for non-root users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md index a5aacd2ca..c2115c1bf 100644 --- a/docs/source/markdown/options/cpu-shares.md +++ b/docs/source/markdown/options/cpu-shares.md @@ -33,3 +33,7 @@ this can result in the following division of CPU shares: | 100 | C0 | 0 | 100% of CPU0 | | 101 | C1 | 1 | 100% of CPU1 | | 102 | C1 | 2 | 100% of CPU2 | + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpuset-cpus.md b/docs/source/markdown/options/cpuset-cpus.md index d717516a0..a67766897 100644 --- a/docs/source/markdown/options/cpuset-cpus.md +++ b/docs/source/markdown/options/cpuset-cpus.md @@ -3,3 +3,7 @@ CPUs in which to allow execution. Can be specified as a comma-separated list (e.g. **0,1**), as a range (e.g. **0-3**), or any combination thereof (e.g. **0-3,7,11-15**). + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpuset-mems.md b/docs/source/markdown/options/cpuset-mems.md index d2d13eb54..1eeab7b13 100644 --- a/docs/source/markdown/options/cpuset-mems.md +++ b/docs/source/markdown/options/cpuset-mems.md @@ -6,3 +6,7 @@ NUMA systems. If there are four memory nodes on the system (0-3), use **--cpuset-mems=0,1** then processes in the container will only use memory from the first two memory nodes. + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error diff --git a/troubleshooting.md b/troubleshooting.md index 6d46a543f..c4ce191ca 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -678,23 +678,28 @@ $ podman run --rootfs /path/to/rootfs:O .... Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. -### 26) Running containers with CPU limits fails with a permissions error +### 26) Running containers with resource limits fails with a permissions error -On some systemd-based systems, non-root users do not have CPU limit delegation -permissions. This causes setting CPU limits to fail. +On some systemd-based systems, non-root users do not have resource limit delegation +permissions. This causes setting resource limits to fail. #### Symptom -Running a container with a CPU limit options such as `--cpus`, `--cpu-period`, -or `--cpu-quota` will fail with an error similar to the following: +Running a container with a resource limit options will fail with an error similar to the following: - Error: opening file `cpu.max` for writing: Permission denied: OCI runtime permission denied error +`--cpus`, `--cpu-period`, `--cpu-quota`, `--cpu-shares`: -This means that CPU limit delegation is not enabled for the current user. + Error: OCI runtime error: crun: the requested cgroup controller `cpu` is not available + +`--cpuset-cpus`, `--cpuset-mems`: + + Error: OCI runtime error: crun: the requested cgroup controller `cpuset` is not available + +This means that resource limit delegation is not enabled for the current user. #### Solution -You can verify whether CPU limit delegation is enabled by running the following command: +You can verify whether resource limit delegation is enabled by running the following command: ```console $ cat "/sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers" @@ -704,19 +709,19 @@ Example output might be: memory pids -In the above example, `cpu` is not listed, which means the current user does -not have permission to set CPU limits. +In the above example, `cpu` and `cpuset` are not listed, which means the current user does +not have permission to set CPU or CPUSET limits. -If you want to enable CPU limit delegation for all users, you can create the +If you want to enable CPU or CPUSET limit delegation for all users, you can create the file `/etc/systemd/system/user@.service.d/delegate.conf` with the contents: ```ini [Service] -Delegate=memory pids cpu io +Delegate=memory pids cpu cpuset ``` -After logging out and logging back in, you should have permission to set CPU -limits. +After logging out and logging back in, you should have permission to set +CPU and CPUSET limits. ### 26) `exec container process '/bin/sh': Exec format error` (or another binary than `bin/sh`) -- cgit v1.2.3-54-g00ecf From eee0ec97e8eb7436208b7852e7e9ee5974384395 Mon Sep 17 00:00:00 2001 From: Ashley Cui Date: Fri, 19 Aug 2022 16:38:49 -0400 Subject: Add quiet/q flag to podman secret ls Add quiet/q flag to podman secret ls, which will print only the secret ID. Signed-off-by: Ashley Cui --- cmd/podman/secrets/list.go | 22 +++++++++++++++++++++- docs/source/markdown/podman-secret-ls.1.md | 6 +++++- test/e2e/secret_test.go | 30 ++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/cmd/podman/secrets/list.go b/cmd/podman/secrets/list.go index 8b1956eab..afa9b8887 100644 --- a/cmd/podman/secrets/list.go +++ b/cmd/podman/secrets/list.go @@ -34,6 +34,7 @@ type listFlagType struct { format string noHeading bool filter []string + quiet bool } func init() { @@ -43,13 +44,20 @@ func init() { }) flags := lsCmd.Flags() + formatFlagName := "format" flags.StringVar(&listFlag.format, formatFlagName, "{{.ID}}\t{{.Name}}\t{{.Driver}}\t{{.CreatedAt}}\t{{.UpdatedAt}}\t\n", "Format volume output using Go template") _ = lsCmd.RegisterFlagCompletionFunc(formatFlagName, common.AutocompleteFormat(&entities.SecretInfoReport{})) + filterFlagName := "filter" flags.StringSliceVarP(&listFlag.filter, filterFlagName, "f", []string{}, "Filter secret output") _ = lsCmd.RegisterFlagCompletionFunc(filterFlagName, common.AutocompleteSecretFilters) - flags.BoolVar(&listFlag.noHeading, "noheading", false, "Do not print headers") + + noHeadingFlagName := "noheading" + flags.BoolVar(&listFlag.noHeading, noHeadingFlagName, false, "Do not print headers") + + quietFlagName := "quiet" + flags.BoolVarP(&listFlag.quiet, quietFlagName, "q", false, "Print secret IDs only") } func ls(cmd *cobra.Command, args []string) error { @@ -76,9 +84,21 @@ func ls(cmd *cobra.Command, args []string) error { Driver: response.Spec.Driver.Name, }) } + + if listFlag.quiet && !cmd.Flags().Changed("format") { + return quietOut(listed) + } + return outputTemplate(cmd, listed) } +func quietOut(responses []*entities.SecretListReport) error { + for _, response := range responses { + fmt.Println(response.ID) + } + return nil +} + func outputTemplate(cmd *cobra.Command, responses []*entities.SecretListReport) error { headers := report.Headers(entities.SecretListReport{}, map[string]string{ "CreatedAt": "CREATED", diff --git a/docs/source/markdown/podman-secret-ls.1.md b/docs/source/markdown/podman-secret-ls.1.md index 3b8535b5d..dcd10c9cf 100644 --- a/docs/source/markdown/podman-secret-ls.1.md +++ b/docs/source/markdown/podman-secret-ls.1.md @@ -30,7 +30,11 @@ Format secret output using Go template. #### **--noheading** -Omit the table headings from the listing of secrets. . +Omit the table headings from the listing of secrets. + +#### **--quiet**, **-q** + +Print secret IDs only. ## EXAMPLES diff --git a/test/e2e/secret_test.go b/test/e2e/secret_test.go index ed328d84a..3360c4059 100644 --- a/test/e2e/secret_test.go +++ b/test/e2e/secret_test.go @@ -145,6 +145,36 @@ var _ = Describe("Podman secret", func() { }) + It("podman secret ls --quiet", func() { + secretFilePath := filepath.Join(podmanTest.TempDir, "secret") + err := ioutil.WriteFile(secretFilePath, []byte("mysecret"), 0755) + Expect(err).To(BeNil()) + + secretName := "a" + + session := podmanTest.Podman([]string{"secret", "create", secretName, secretFilePath}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + secretID := session.OutputToString() + + list := podmanTest.Podman([]string{"secret", "ls", "-q"}) + list.WaitWithDefaultTimeout() + Expect(list).Should(Exit(0)) + Expect(list.OutputToString()).To(Equal(secretID)) + + list = podmanTest.Podman([]string{"secret", "ls", "--quiet"}) + list.WaitWithDefaultTimeout() + Expect(list).Should(Exit(0)) + Expect(list.OutputToString()).To(Equal(secretID)) + + // Prefer format over quiet + list = podmanTest.Podman([]string{"secret", "ls", "-q", "--format", "{{.Name}}"}) + list.WaitWithDefaultTimeout() + Expect(list).Should(Exit(0)) + Expect(list.OutputToString()).To(Equal(secretName)) + + }) + It("podman secret ls with filters", func() { secretFilePath := filepath.Join(podmanTest.TempDir, "secret") err := ioutil.WriteFile(secretFilePath, []byte("mysecret"), 0755) -- cgit v1.2.3-54-g00ecf From fbe2bd87b0581bdd1651689b9b8a01d0d5116517 Mon Sep 17 00:00:00 2001 From: Valentin Rothberg Date: Mon, 22 Aug 2022 14:53:57 +0200 Subject: [CI:DOCS] elaborate on image lookups of foreign platforms After pulling/creating an image of a foreign platform, Podman will happily use it when looking it up in the local storage and will not pull down the image matching the host platform. As discussed in #12682, the reasoning for it is Docker compatibility and the fact that user already rely on the behavior. While Podman is now emitting a warning when an image is in use not matching the local platform, the documentation was lacking that information. Fixes: #15300 Signed-off-by: Valentin Rothberg --- docs/source/markdown/options/arch.md | 1 + docs/source/markdown/options/platform.md | 1 + docs/source/markdown/podman-build.1.md.in | 17 +++++++++++------ docs/source/markdown/podman-create.1.md.in | 1 + docs/source/markdown/podman-pull.1.md.in | 1 + docs/source/markdown/podman-run.1.md.in | 1 + 6 files changed, 16 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md index 005197707..76fb349a0 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,2 +1,3 @@ #### **--arch**=*ARCH* Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`. +Unless overridden, subsequent lookups of the same image in the local storage will match this architecture, regardless of the host. diff --git a/docs/source/markdown/options/platform.md b/docs/source/markdown/options/platform.md index edfa428ff..b66efdfb2 100644 --- a/docs/source/markdown/options/platform.md +++ b/docs/source/markdown/options/platform.md @@ -2,3 +2,4 @@ Specify the platform for selecting the image. (Conflicts with --arch and --os) The `--platform` option can be used to override the current architecture and operating system. +Unless overridden, subsequent lookups of the same image in the local storage will match this platform, regardless of the host. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index b49beb3bf..350930adf 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -65,8 +65,9 @@ discarded when writing images in Docker formats. Set the architecture of the image to be built, and that of the base image to be 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) +architecture of the build host. Unless overridden, subsequent lookups of the +same image in the local storage will match this architecture, regardless of the +host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x) @@option authfile @@ -454,7 +455,8 @@ do not include `History` information in their images. Set the OS of the image to be built, and that of the base image to be pulled, if the build uses one, instead of using the current operating system of the -build host. +build host. Unless overridden, subsequent lookups of the same image in the +local storage will match this OS, regardless of the host. #### **--os-feature**=*feature* @@ -506,9 +508,12 @@ process. Set the *os/arch* of the built image (and its base image, if your build uses one) to the provided value instead of using the current operating system and -architecture of the host (for example `linux/arm`). If `--platform` is set, -then the values of the `--arch`, `--os`, and `--variant` options will be -overridden. +architecture of the host (for example `linux/arm`). Unless overridden, +subsequent lookups of the same image in the local storage will match this +platform, regardless of the host. + +If `--platform` is set, then the values of the `--arch`, `--os`, and +`--variant` options will be overridden. The `--platform` option can be specified more than once, or given a comma-separated list of values as its argument. When more than one platform is diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 3e6b07225..7ec4fc66f 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -452,6 +452,7 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option passwd-entry diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index cf06cc6a8..e3e619de5 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -77,6 +77,7 @@ Print the usage statement. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option platform diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 1c02eafe9..d10520e35 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -465,6 +465,7 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. #### **--passwd** -- cgit v1.2.3-54-g00ecf From bd90818b02309bbda3fd953e8f6e574970e6918b Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 07:32:36 -0600 Subject: Man pages: refactor common options: --creds Refactor the --creds option. I went with the one in podman-pull The main difference between all of them is the '####' line, differences in the param descriptions. podman-pull had the clearest one. This is another one that hack/markdown-preprocess-review is good for reviewing. Signed-off-by: Ed Santiago --- docs/source/markdown/options/creds.md | 5 +++++ docs/source/markdown/podman-build.1.md.in | 6 +----- docs/source/markdown/podman-container-runlabel.1.md.in | 4 +--- docs/source/markdown/podman-kube-play.1.md.in | 6 +----- docs/source/markdown/podman-manifest-add.1.md.in | 6 +----- docs/source/markdown/podman-manifest-push.1.md.in | 6 +----- docs/source/markdown/podman-pull.1.md.in | 6 +----- docs/source/markdown/podman-push.1.md.in | 6 +----- 8 files changed, 12 insertions(+), 33 deletions(-) create mode 100644 docs/source/markdown/options/creds.md (limited to 'docs') diff --git a/docs/source/markdown/options/creds.md b/docs/source/markdown/options/creds.md new file mode 100644 index 000000000..23399dda4 --- /dev/null +++ b/docs/source/markdown/options/creds.md @@ -0,0 +1,5 @@ +#### **--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. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index c29cf997d..772567e53 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -195,11 +195,7 @@ Set additional flags to pass to the C Preprocessor cpp(1). Containerfiles ending @@option cpuset-mems -#### **--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. +@@option creds #### **--decryption-key**=*key[:passphrase]* diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in index 7f462bf70..59eb48fd3 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md.in +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -37,9 +37,7 @@ Will be replaced with the current working directory. 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. +@@option creds #### **--display** diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 14c5f2498..1b9544fb6 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -130,11 +130,7 @@ Note: The *--configmap* option can be used multiple times or a comma-separated l Use *path* as the build context directory for each image. Requires --build option be true. (This option is not available with the remote Podman client) -#### **--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. +@@option creds #### **--help**, **-h** diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index a1c498e4f..adffe1875 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -40,11 +40,7 @@ retrieved from the image's configuration information. 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. +@@option creds #### **--features** diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in index 631ead376..515f07207 100644 --- a/docs/source/markdown/podman-manifest-push.1.md.in +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -30,11 +30,7 @@ Please refer to containers-certs.d(5) for details. (This option is not available 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. +@@option creds #### **--digestfile**=*Digestfile* diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 46eaa706a..5d875590f 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -55,11 +55,7 @@ All tagged images in the repository will be pulled. @@option cert-dir -#### **--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. +@@option creds #### **--disable-content-trust** diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index 1c936cd66..f32261bab 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -63,11 +63,7 @@ Note: This flag can only be set when using the **dir** transport 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. +@@option creds #### **--digestfile**=*Digestfile* -- cgit v1.2.3-54-g00ecf From 46f31361f88317d405d7f7b41c5d644328cd2e5b Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 10:18:36 -0600 Subject: Man pages: refactor common options: --cidfile There are two meanings: one writes a cidfile, the other reads. Split into two .md files. This can be reviewed with hack/markdown-preprocess-review . The main differences you'll see are all in cidfile.read: 1) I use the <> feature. This works nicely for kill, pause/unpause, and stop. It works less nicely for rm, because the man page will show "...and rm the container" (a human might prefer to see "REMOVE the container"). Given the benefit of this cleanup, I think this is a fine tradeoff. 2) I choose to include the "multiple times" text even on man pages where it wasn't present before. I tested to make sure it works. 3) The #### line I choose is IMHO the best one. Minor differences: * I believe the "remove the container" text in podman-kill and podman-stop is a copy/paste error. This PR fixes it. * The only differences between the cidfile.write texts is the #### line (my version is best) and a final period. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 5 + docs/source/markdown/options/cidfile.read.md | 4 + docs/source/markdown/options/cidfile.write.md | 3 + docs/source/markdown/podman-create.1.md.in | 4 +- docs/source/markdown/podman-kill.1.md | 70 -------------- docs/source/markdown/podman-kill.1.md.in | 68 ++++++++++++++ docs/source/markdown/podman-pause.1.md | 85 ----------------- docs/source/markdown/podman-pause.1.md.in | 83 ++++++++++++++++ docs/source/markdown/podman-rm.1.md | 130 -------------------------- docs/source/markdown/podman-rm.1.md.in | 128 +++++++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 4 +- docs/source/markdown/podman-stop.1.md | 89 ------------------ docs/source/markdown/podman-stop.1.md.in | 87 +++++++++++++++++ docs/source/markdown/podman-unpause.1.md | 85 ----------------- docs/source/markdown/podman-unpause.1.md.in | 83 ++++++++++++++++ 15 files changed, 463 insertions(+), 465 deletions(-) create mode 100644 docs/source/markdown/options/cidfile.read.md create mode 100644 docs/source/markdown/options/cidfile.write.md delete mode 100644 docs/source/markdown/podman-kill.1.md create mode 100644 docs/source/markdown/podman-kill.1.md.in delete mode 100644 docs/source/markdown/podman-pause.1.md create mode 100644 docs/source/markdown/podman-pause.1.md.in delete mode 100644 docs/source/markdown/podman-rm.1.md create mode 100644 docs/source/markdown/podman-rm.1.md.in delete mode 100644 docs/source/markdown/podman-stop.1.md create mode 100644 docs/source/markdown/podman-stop.1.md.in delete mode 100644 docs/source/markdown/podman-unpause.1.md create mode 100644 docs/source/markdown/podman-unpause.1.md.in (limited to 'docs') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 70f1c2bd7..5a30aab78 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -4,14 +4,19 @@ podman-container-clone.1.md podman-container-runlabel.1.md podman-create.1.md podman-image-sign.1.md +podman-kill.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-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md podman-pull.1.md podman-push.1.md +podman-rm.1.md podman-run.1.md podman-search.1.md +podman-stop.1.md +podman-unpause.1.md diff --git a/docs/source/markdown/options/cidfile.read.md b/docs/source/markdown/options/cidfile.read.md new file mode 100644 index 000000000..414700fca --- /dev/null +++ b/docs/source/markdown/options/cidfile.read.md @@ -0,0 +1,4 @@ +#### **--cidfile**=*file* + +Read container ID from the specified *file* and <> the container. +Can be specified multiple times. diff --git a/docs/source/markdown/options/cidfile.write.md b/docs/source/markdown/options/cidfile.write.md new file mode 100644 index 000000000..b5e7435b2 --- /dev/null +++ b/docs/source/markdown/options/cidfile.write.md @@ -0,0 +1,3 @@ +#### **--cidfile**=*file* + +Write the container ID to *file*. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 7ec4fc66f..2827964f7 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -105,9 +105,7 @@ Block IO relative device weight. @@option chrootdirs -#### **--cidfile**=*id* - -Write the container ID to the file +@@option cidfile.write @@option conmon-pidfile diff --git a/docs/source/markdown/podman-kill.1.md b/docs/source/markdown/podman-kill.1.md deleted file mode 100644 index a4f80ac81..000000000 --- a/docs/source/markdown/podman-kill.1.md +++ /dev/null @@ -1,70 +0,0 @@ -% podman-kill(1) - -## NAME -podman\-kill - Kill the main process in one or more containers - -## SYNOPSIS -**podman kill** [*options*] [*container* ...] - -**podman container kill** [*options*] [*container* ...] - -## DESCRIPTION -The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal. - -## OPTIONS -#### **--all**, **-a** - -Signal all running and paused containers. - -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--signal**, **-s** - -Signal to send to the container. For more information on Linux signals, refer to *man signal(7)*. - - -## EXAMPLE - -Kill container with a given name -``` -podman kill mywebserver -``` - -Kill container with a given ID -``` -podman kill 860a4b23 -``` - -Terminate container by sending `TERM` signal -``` -podman kill --signal TERM 860a4b23 -``` - -Kill the latest container created by Podman -``` -podman kill --latest -``` - -Terminate all containers by sending `KILL` signal -``` -podman kill --signal KILL -a -``` - -Kill container using ID specified in a given files -``` -podman kill --cidfile /home/user/cidfile-1 -podman kill --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-stop(1)](podman-stop.1.md)** - -## HISTORY -September 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-kill.1.md.in b/docs/source/markdown/podman-kill.1.md.in new file mode 100644 index 000000000..2788cc694 --- /dev/null +++ b/docs/source/markdown/podman-kill.1.md.in @@ -0,0 +1,68 @@ +% podman-kill(1) + +## NAME +podman\-kill - Kill the main process in one or more containers + +## SYNOPSIS +**podman kill** [*options*] [*container* ...] + +**podman container kill** [*options*] [*container* ...] + +## DESCRIPTION +The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal. + +## OPTIONS +#### **--all**, **-a** + +Signal all running and paused containers. + +@@option cidfile.read + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--signal**, **-s** + +Signal to send to the container. For more information on Linux signals, refer to *man signal(7)*. + + +## EXAMPLE + +Kill container with a given name +``` +podman kill mywebserver +``` + +Kill container with a given ID +``` +podman kill 860a4b23 +``` + +Terminate container by sending `TERM` signal +``` +podman kill --signal TERM 860a4b23 +``` + +Kill the latest container created by Podman +``` +podman kill --latest +``` + +Terminate all containers by sending `KILL` signal +``` +podman kill --signal KILL -a +``` + +Kill container using ID specified in a given files +``` +podman kill --cidfile /home/user/cidfile-1 +podman kill --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-stop(1)](podman-stop.1.md)** + +## HISTORY +September 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-pause.1.md b/docs/source/markdown/podman-pause.1.md deleted file mode 100644 index f374d96f3..000000000 --- a/docs/source/markdown/podman-pause.1.md +++ /dev/null @@ -1,85 +0,0 @@ -% podman-pause(1) - -## NAME -podman\-pause - Pause one or more containers - -## SYNOPSIS -**podman pause** [*options*] [*container*...] - -**podman container pause** [*options*] [*container*...] - -## DESCRIPTION -Pauses all the processes in one or more containers. You may use container IDs or names as input. - -## OPTIONS - -#### **--all**, **-a** - -Pause all running containers. - -#### **--cidfile** - -Read container ID from the specified file and pause the container. Can be specified multiple times. - -#### **--filter**, **-f**=*filter* - -Filter what containers pause. -Multiple filters can be given with multiple uses of the --filter flag. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. - -Valid filters are listed below: - -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID (accepts regex) | -| name | [Name] Container's name (accepts regex) | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | -| pod | [Pod] name or full or partial ID of pod | -| network | [Network] name or full ID of network | - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -## EXAMPLE - -Pause container named 'mywebserver' -``` -podman pause mywebserver -``` - -Pause container by partial container ID. -``` -podman pause 860a4b23 -``` - -Pause all **running** containers. -``` -podman pause --all -``` - -Pause container using ID specified in a given files. -``` -podman pause --cidfile /home/user/cidfile-1 -podman pause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 -``` - -Pause the latest container created by Podman. -``` -podman pause --latest -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-unpause(1)](podman-unpause.1.md)** - -## HISTORY -September 2017, Originally compiled by Dan Walsh diff --git a/docs/source/markdown/podman-pause.1.md.in b/docs/source/markdown/podman-pause.1.md.in new file mode 100644 index 000000000..af308f034 --- /dev/null +++ b/docs/source/markdown/podman-pause.1.md.in @@ -0,0 +1,83 @@ +% podman-pause(1) + +## NAME +podman\-pause - Pause one or more containers + +## SYNOPSIS +**podman pause** [*options*] [*container*...] + +**podman container pause** [*options*] [*container*...] + +## DESCRIPTION +Pauses all the processes in one or more containers. You may use container IDs or names as input. + +## OPTIONS + +#### **--all**, **-a** + +Pause all running containers. + +@@option cidfile.read + +#### **--filter**, **-f**=*filter* + +Filter what containers pause. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +## EXAMPLE + +Pause container named 'mywebserver' +``` +podman pause mywebserver +``` + +Pause container by partial container ID. +``` +podman pause 860a4b23 +``` + +Pause all **running** containers. +``` +podman pause --all +``` + +Pause container using ID specified in a given files. +``` +podman pause --cidfile /home/user/cidfile-1 +podman pause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + +Pause the latest container created by Podman. +``` +podman pause --latest +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-unpause(1)](podman-unpause.1.md)** + +## HISTORY +September 2017, Originally compiled by Dan Walsh diff --git a/docs/source/markdown/podman-rm.1.md b/docs/source/markdown/podman-rm.1.md deleted file mode 100644 index 1dbd1d0c3..000000000 --- a/docs/source/markdown/podman-rm.1.md +++ /dev/null @@ -1,130 +0,0 @@ -% podman-rm(1) - -## NAME -podman\-rm - Remove one or more containers - -## SYNOPSIS -**podman rm** [*options*] *container* - -**podman container rm** [*options*] *container* - -## DESCRIPTION -**podman rm** will remove one or more containers from the host. The container name or ID can be used. This does not remove images. -Running or unusable containers will not be removed without the **-f** option. - -## OPTIONS - -#### **--all**, **-a** - -Remove all containers. Can be used in conjunction with **-f** as well. - -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. - -#### **--depend** - -Remove selected container and recursively remove all containers that depend on it. - -#### **--filter**=*filter* - -Filter what containers remove. -Multiple filters can be given with multiple uses of the --filter flag. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. - -Valid filters are listed below: - -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID (accepts regex) | -| name | [Name] Container's name (accepts regex) | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | -| pod | [Pod] name or full or partial ID of pod | -| network | [Network] name or full ID of network | - -#### **--force**, **-f** - -Force the removal of running and paused containers. Forcing a container removal also -removes containers from container storage even if the container is not known to podman. -Containers could have been created by a different container engine. -In addition, forcing can be used to remove unusable containers, e.g. containers -whose OCI runtime has become unavailable. - -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping the container. The --force option must be specified to use the --time option. - -#### **--volumes**, **-v** - -Remove anonymous volumes associated with the container. This does not include named volumes -created with **podman volume create**, or the **--volume** option of **podman run** and **podman create**. - -## EXAMPLE -Remove a container by its name *mywebserver* -``` -$ podman rm mywebserver -``` - -Remove a *mywebserver* container and all of the containers that depend on it -``` -$ podman rm --depend mywebserver -``` - -Remove several containers by name and container id. -``` -$ podman rm mywebserver myflaskserver 860a4b23 -``` - -Remove several containers reading their IDs from files. -``` -$ podman rm --cidfile ./cidfile-1 --cidfile /home/user/cidfile-2 -``` - -Forcibly remove a container by container ID. -``` -$ podman rm -f 860a4b23 -``` - -Remove all containers regardless of its run state. -``` -$ podman rm -f -a -``` - -Forcibly remove the latest container created. -``` -$ podman rm -f --latest -``` - -## Exit Status - **0** All specified containers removed - - **1** One of the specified containers did not exist, and no other failures - - **2** One of the specified containers is paused or running - - **125** The command fails for any other reason - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[crio(8)](https://github.com/cri-o/cri-o/blob/main/docs/crio.8.md)** - -## HISTORY -August 2017, Originally compiled by Ryan Cole diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in new file mode 100644 index 000000000..fa3031b29 --- /dev/null +++ b/docs/source/markdown/podman-rm.1.md.in @@ -0,0 +1,128 @@ +% podman-rm(1) + +## NAME +podman\-rm - Remove one or more containers + +## SYNOPSIS +**podman rm** [*options*] *container* + +**podman container rm** [*options*] *container* + +## DESCRIPTION +**podman rm** will remove one or more containers from the host. The container name or ID can be used. This does not remove images. +Running or unusable containers will not be removed without the **-f** option. + +## OPTIONS + +#### **--all**, **-a** + +Remove all containers. Can be used in conjunction with **-f** as well. + +@@option cidfile.read + +#### **--depend** + +Remove selected container and recursively remove all containers that depend on it. + +#### **--filter**=*filter* + +Filter what containers remove. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--force**, **-f** + +Force the removal of running and paused containers. Forcing a container removal also +removes containers from container storage even if the container is not known to podman. +Containers could have been created by a different container engine. +In addition, forcing can be used to remove unusable containers, e.g. containers +whose OCI runtime has become unavailable. + +#### **--ignore**, **-i** + +Ignore errors when specified containers are not in the container store. A user +might have decided to manually remove a container which would lead to a failure +during the ExecStop directive of a systemd service referencing that container. + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping the container. The --force option must be specified to use the --time option. + +#### **--volumes**, **-v** + +Remove anonymous volumes associated with the container. This does not include named volumes +created with **podman volume create**, or the **--volume** option of **podman run** and **podman create**. + +## EXAMPLE +Remove a container by its name *mywebserver* +``` +$ podman rm mywebserver +``` + +Remove a *mywebserver* container and all of the containers that depend on it +``` +$ podman rm --depend mywebserver +``` + +Remove several containers by name and container id. +``` +$ podman rm mywebserver myflaskserver 860a4b23 +``` + +Remove several containers reading their IDs from files. +``` +$ podman rm --cidfile ./cidfile-1 --cidfile /home/user/cidfile-2 +``` + +Forcibly remove a container by container ID. +``` +$ podman rm -f 860a4b23 +``` + +Remove all containers regardless of its run state. +``` +$ podman rm -f -a +``` + +Forcibly remove the latest container created. +``` +$ podman rm -f --latest +``` + +## Exit Status + **0** All specified containers removed + + **1** One of the specified containers did not exist, and no other failures + + **2** One of the specified containers is paused or running + + **125** The command fails for any other reason + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[crio(8)](https://github.com/cri-o/cri-o/blob/main/docs/crio.8.md)** + +## HISTORY +August 2017, Originally compiled by Ryan Cole diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index d10520e35..cdfa9366a 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -120,9 +120,7 @@ each of **stdin**, **stdout**, and **stderr**. @@option chrootdirs -#### **--cidfile**=*file* - -Write the container ID to *file*. +@@option cidfile.write @@option conmon-pidfile diff --git a/docs/source/markdown/podman-stop.1.md b/docs/source/markdown/podman-stop.1.md deleted file mode 100644 index cfc49afa1..000000000 --- a/docs/source/markdown/podman-stop.1.md +++ /dev/null @@ -1,89 +0,0 @@ -% podman-stop(1) - -## NAME -podman\-stop - Stop one or more running containers - -## SYNOPSIS -**podman stop** [*options*] *container* ... - -**podman container stop** [*options*] *container* ... - -## DESCRIPTION -Stops one or more containers. You may use container IDs or names as input. The **--time** switch -allows you to specify the number of seconds to wait before forcibly stopping the container after the stop command -is issued to the container. The default is 10 seconds. By default, containers are stopped with SIGTERM -and then SIGKILL after the timeout. The SIGTERM default can be overridden by the image used to create the -container and also via command line when creating the container. - -## OPTIONS - -#### **--all**, **-a** - -Stop all running containers. This does not include paused containers. - -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. - -#### **--filter**, **-f**=*filter* - -Filter what containers are going to be stopped. -Multiple filters can be given with multiple uses of the --filter flag. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. - -Valid filters are listed below: - -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID (accepts regex) | -| name | [Name] Container's name (accepts regex) | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | -| pod | [Pod] name or full or partial ID of pod | -| network | [Network] name or full ID of network | - -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping the container - -## EXAMPLES - -$ podman stop mywebserver - -$ podman stop 860a4b235279 - -$ podman stop mywebserver 860a4b235279 - -$ podman stop --cidfile /home/user/cidfile-1 - -$ podman stop --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 - -$ podman stop --time 2 860a4b235279 - -$ podman stop -a - -$ podman stop --latest - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-rm(1)](podman-rm.1.md)** - -## HISTORY -September 2018, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-stop.1.md.in b/docs/source/markdown/podman-stop.1.md.in new file mode 100644 index 000000000..04fc9387f --- /dev/null +++ b/docs/source/markdown/podman-stop.1.md.in @@ -0,0 +1,87 @@ +% podman-stop(1) + +## NAME +podman\-stop - Stop one or more running containers + +## SYNOPSIS +**podman stop** [*options*] *container* ... + +**podman container stop** [*options*] *container* ... + +## DESCRIPTION +Stops one or more containers. You may use container IDs or names as input. The **--time** switch +allows you to specify the number of seconds to wait before forcibly stopping the container after the stop command +is issued to the container. The default is 10 seconds. By default, containers are stopped with SIGTERM +and then SIGKILL after the timeout. The SIGTERM default can be overridden by the image used to create the +container and also via command line when creating the container. + +## OPTIONS + +#### **--all**, **-a** + +Stop all running containers. This does not include paused containers. + +@@option cidfile.read + +#### **--filter**, **-f**=*filter* + +Filter what containers are going to be stopped. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--ignore**, **-i** + +Ignore errors when specified containers are not in the container store. A user +might have decided to manually remove a container which would lead to a failure +during the ExecStop directive of a systemd service referencing that container. + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping the container + +## EXAMPLES + +$ podman stop mywebserver + +$ podman stop 860a4b235279 + +$ podman stop mywebserver 860a4b235279 + +$ podman stop --cidfile /home/user/cidfile-1 + +$ podman stop --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 + +$ podman stop --time 2 860a4b235279 + +$ podman stop -a + +$ podman stop --latest + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-rm(1)](podman-rm.1.md)** + +## HISTORY +September 2018, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-unpause.1.md b/docs/source/markdown/podman-unpause.1.md deleted file mode 100644 index b94ace89e..000000000 --- a/docs/source/markdown/podman-unpause.1.md +++ /dev/null @@ -1,85 +0,0 @@ -% podman-unpause(1) - -## NAME -podman\-unpause - Unpause one or more containers - -## SYNOPSIS -**podman unpause** [*options*]|[*container* ...] - -**podman container unpause** [*options*]|[*container* ...] - -## DESCRIPTION -Unpauses the processes in one or more containers. You may use container IDs or names as input. - -## OPTIONS - -#### **--all**, **-a** - -Unpause all paused containers. - -#### **--cidfile** - -Read container ID from the specified file and unpause the container. Can be specified multiple times. - -#### **--filter**, **-f**=*filter* - -Filter what containers unpause. -Multiple filters can be given with multiple uses of the --filter flag. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. - -Valid filters are listed below: - -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID (accepts regex) | -| name | [Name] Container's name (accepts regex) | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | -| pod | [Pod] name or full or partial ID of pod | -| network | [Network] name or full ID of network | - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -## EXAMPLE - -Unpause container called 'mywebserver' -``` -podman unpause mywebserver -``` - -Unpause container by a partial container ID. -``` -podman unpause 860a4b23 -``` - -Unpause all **paused** containers. -``` -podman unpause --all -``` - -Unpause container using ID specified in a given files. -``` -podman unpause --cidfile /home/user/cidfile-1 -podman unpause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 -``` - -Unpause the latest container created by Podman. -``` -podman unpause --latest -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pause(1)](podman-pause.1.md)** - -## HISTORY -September 2017, Originally compiled by Dan Walsh diff --git a/docs/source/markdown/podman-unpause.1.md.in b/docs/source/markdown/podman-unpause.1.md.in new file mode 100644 index 000000000..7bd46e171 --- /dev/null +++ b/docs/source/markdown/podman-unpause.1.md.in @@ -0,0 +1,83 @@ +% podman-unpause(1) + +## NAME +podman\-unpause - Unpause one or more containers + +## SYNOPSIS +**podman unpause** [*options*]|[*container* ...] + +**podman container unpause** [*options*]|[*container* ...] + +## DESCRIPTION +Unpauses the processes in one or more containers. You may use container IDs or names as input. + +## OPTIONS + +#### **--all**, **-a** + +Unpause all paused containers. + +@@option cidfile.read + +#### **--filter**, **-f**=*filter* + +Filter what containers unpause. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +## EXAMPLE + +Unpause container called 'mywebserver' +``` +podman unpause mywebserver +``` + +Unpause container by a partial container ID. +``` +podman unpause 860a4b23 +``` + +Unpause all **paused** containers. +``` +podman unpause --all +``` + +Unpause container using ID specified in a given files. +``` +podman unpause --cidfile /home/user/cidfile-1 +podman unpause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + +Unpause the latest container created by Podman. +``` +podman unpause --latest +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pause(1)](podman-pause.1.md)** + +## HISTORY +September 2017, Originally compiled by Dan Walsh -- cgit v1.2.3-54-g00ecf From c6488fe4afc80ad7cc1d98484220f225b7c1cd9a Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 12:31:02 -0600 Subject: Man pages: fix sloppiness I've been doing the man-page cleanup distractedly, while fighting other fires, and submitted some crap: * #15339: I used single angle brackets, not double * #15407: I only refactored --cert-dir from some man pages, not all Easy to review with hack/markdown-preprocess-review, because all the removed texts are identical. The only diff is that container-certs.d is now a link. Sorry about that. I'm going to spend more time being careful. Signed-off-by: Ed Santiago --- docs/source/markdown/options/annotation.container.md | 2 +- docs/source/markdown/podman-container-runlabel.1.md.in | 5 +---- docs/source/markdown/podman-image-sign.1.md.in | 5 +---- docs/source/markdown/podman-login.1.md.in | 5 +---- docs/source/markdown/podman-manifest-add.1.md.in | 5 +---- docs/source/markdown/podman-manifest-push.1.md.in | 5 +---- docs/source/markdown/podman-push.1.md.in | 5 +---- 7 files changed, 7 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/options/annotation.container.md b/docs/source/markdown/options/annotation.container.md index bd561a15f..0d155e5e4 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -1,3 +1,3 @@ #### **--annotation**=*key=value* -Add an annotation to the container<| or pod>. This option can be set multiple times. +Add an annotation to the container<<| or pod>>. This option can be set multiple times. diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in index 59eb48fd3..f5fb8ca60 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md.in +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -32,10 +32,7 @@ Will be replaced with the current working directory. @@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) +@@option cert-dir @@option creds diff --git a/docs/source/markdown/podman-image-sign.1.md.in b/docs/source/markdown/podman-image-sign.1.md.in index 340cdbd21..d5efabc1a 100644 --- a/docs/source/markdown/podman-image-sign.1.md.in +++ b/docs/source/markdown/podman-image-sign.1.md.in @@ -21,10 +21,7 @@ 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) +@@option cert-dir #### **--directory**, **-d**=*dir* diff --git a/docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md.in index 6ec207a1e..4537988eb 100644 --- a/docs/source/markdown/podman-login.1.md.in +++ b/docs/source/markdown/podman-login.1.md.in @@ -30,10 +30,7 @@ For more details about format and configurations of the auth.json file, please r @@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) +@@option cert-dir #### **--get-login** diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index adffe1875..e82c04985 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -35,10 +35,7 @@ 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) +@@option cert-dir @@option creds diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in index 515f07207..88d070c3f 100644 --- a/docs/source/markdown/podman-manifest-push.1.md.in +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -21,10 +21,7 @@ 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) +@@option cert-dir #### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index f32261bab..b7d05d988 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -49,10 +49,7 @@ $ podman push myimage oci-archive:/tmp/myimage @@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) +@@option cert-dir #### **--compress** -- cgit v1.2.3-54-g00ecf From 0f768cef3b2a7ca0f2e60c78c7f7f1ffd8e048ae Mon Sep 17 00:00:00 2001 From: Toshiki Sonoda Date: Tue, 23 Aug 2022 08:47:02 +0900 Subject: [CI:DOCS] Update Troubleshooting.md - Fix the item number - Fix the links Signed-off-by: Toshiki Sonoda --- docs/source/markdown/podman-create.1.md.in | 2 +- docs/source/markdown/podman-run.1.md.in | 2 +- troubleshooting.md | 24 ++++++++++++------------ 3 files changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 7ec4fc66f..fa76541c2 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -129,7 +129,7 @@ for **--cpu-period** and **--cpu-quota**, so you may only set either On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error @@option cpuset-cpus diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index d10520e35..6bed01200 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -144,7 +144,7 @@ for **--cpu-period** and **--cpu-quota**, so you may only set either On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error @@option cpuset-cpus diff --git a/troubleshooting.md b/troubleshooting.md index c4ce191ca..0e767926b 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -723,13 +723,13 @@ Delegate=memory pids cpu cpuset After logging out and logging back in, you should have permission to set CPU and CPUSET limits. -### 26) `exec container process '/bin/sh': Exec format error` (or another binary than `bin/sh`) +### 27) `exec container process '/bin/sh': Exec format error` (or another binary than `bin/sh`) This can happen when running a container from an image for another architecture than the one you are running on. For example, if a remote repository only has, and thus send you, a `linux/arm64` _OS/ARCH_ but you run on `linux/amd64` (as happened in https://github.com/openMF/community-app/issues/3323 due to https://github.com/timbru31/docker-ruby-node/issues/564). -### 27) `Error: failed to create sshClient: Connection to bastion host (ssh://user@host:22/run/user/.../podman/podman.sock) failed.: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain` +### 28) `Error: failed to create sshClient: Connection to bastion host (ssh://user@host:22/run/user/.../podman/podman.sock) failed.: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain` In some situations where the client is not on the same machine as where the podman daemon is running the client key could be using a cipher not supported by the host. This indicates an issue with one's SSH config. Until remedied using podman over ssh with a pre-shared key will be impossible. @@ -766,7 +766,7 @@ And now this should work: $ podman-remote info ``` -### 28) Rootless CNI networking fails in RHEL with Podman v2.2.1 to v3.0.1. +### 29) Rootless CNI networking fails in RHEL with Podman v2.2.1 to v3.0.1. A failure is encountered when trying to use networking on a rootless container in Podman v2.2.1 through v3.0.1 on RHEL. This error does not @@ -785,7 +785,7 @@ instructions for building the Infra container image can be found for v2.2.1 [here](https://github.com/containers/podman/tree/v2.2.1-rhel/contrib/rootless-cni-infra), and for v3.0.1 [here](https://github.com/containers/podman/tree/v3.0.1-rhel/contrib/rootless-cni-infra). -### 29) Container related firewall rules are lost after reloading firewalld +### 30) Container related firewall rules are lost after reloading firewalld Container network can't be reached after `firewall-cmd --reload` and `systemctl restart firewalld` Running `podman network reload` will fix it but it has to be done manually. #### Symptom @@ -923,7 +923,7 @@ if __name__ == "__main__": signal_listener() ``` -### 30) Podman run fails with `ERRO[0000] XDG_RUNTIME_DIR directory "/run/user/0" is not owned by the current user` or `Error: error creating tmpdir: mkdir /run/user/1000: permission denied`. +### 31) Podman run fails with `ERRO[0000] XDG_RUNTIME_DIR directory "/run/user/0" is not owned by the current user` or `Error: error creating tmpdir: mkdir /run/user/1000: permission denied`. A failure is encountered when performing `podman run` with a warning `XDG_RUNTIME_DIR is pointing to a path which is not writable. Most likely podman will fail.` @@ -965,7 +965,7 @@ Alternatives: * Before invoking Podman command create a valid login session for your rootless user using `loginctl enable-linger ` -### 31) 127.0.0.1:7777 port already bound +### 32) 127.0.0.1:7777 port already bound After deleting a VM on macOS, the initialization of subsequent VMs fails. @@ -977,7 +977,7 @@ After deleting a client VM on macOS via `podman machine stop` && `podman machine You will need to remove the hanging gv-proxy process bound to the port in question. For example, if the port mentioned in the error message is 127.0.0.1:7777, you can use the command `kill -9 $(lsof -i:7777)` in order to identify and remove the hanging process which prevents you from starting a new VM on that default port. -### 32) The sshd process fails to run inside of the container. +### 33) The sshd process fails to run inside of the container. #### Symptom @@ -996,7 +996,7 @@ then using podman -remote to start the container or simply by running something like `systemd-run podman run ...`. In this case the container will only need `CAP_AUDIT_WRITE`. -### 33) Container creates a file that is not owned by the user's regular UID +### 34) Container creates a file that is not owned by the user's regular UID After running a container with rootless Podman, the non-root user sees a numerical UID and GID instead of a username and groupname. @@ -1111,7 +1111,7 @@ Another variant of the same problem could occur when using in some way (e.g by creating them themselves, or switching the effective UID to a rootless user and then creates files). -### 34) Passed-in devices or files can't be accessed in rootless container (UID/GID mapping problem) +### 35) Passed-in devices or files can't be accessed in rootless container (UID/GID mapping problem) As a non-root user you have access rights to devices, files and directories that you want to pass into a rootless container with `--device=...`, `--volume=...` or `--mount=..`. @@ -1208,7 +1208,7 @@ can sometimes be an alternative solution, but it forces the regular user's host UID to be mapped to the same UID inside the container so it provides less flexibility than using `--uidmap` and `--gidmap`. -### 35) Images in the additional stores can be deleted even if there are containers using them +### 36) Images in the additional stores can be deleted even if there are containers using them When an image in an additional store is used, it is not locked thus it can be deleted even if there are containers using it. @@ -1223,7 +1223,7 @@ It is the user responsibility to make sure images in an additional store are not deleted while being used by containers in another store. -### 36) Syncing bugfixes for podman-remote or setups using Podman API +### 37) Syncing bugfixes for podman-remote or setups using Podman API After upgrading Podman to a newer version an issue with the earlier version of Podman still presents itself while using podman-remote. @@ -1237,7 +1237,7 @@ When upgrading Podman to a particular version for the required fixes, users ofte Example: If a particular bug was fixed in `v4.1.0` then the Podman client must have version `v4.1.0` as well the Podman server must have version `v4.1.0`. -### 37) Unexpected carriage returns are outputted on the terminal +### 38) Unexpected carriage returns are outputted on the terminal When using the __--tty__ (__-t__) flag, unexpected carriage returns are outputted on the terminal. -- cgit v1.2.3-54-g00ecf From 74388fe75ffa896993256c5336dabaa071b034f9 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 13:06:49 -0600 Subject: Man pages: refactor common options: --pod-id-file Much like --cidfile (#15414), --pod-id-file has two meanings. One is used in pod-related commands, one in container ones. Both meanings read the file, so the read/write split used in --cidfile is not applicable here. podman-pod-create keeps its --pod-id-file option because that one cannot be refactored: that's the only command (now) that writes a pod-id file. Reviewable using hack/markdown-preprocess-review but I did take some liberties with the #### args because they were wrong. And, since I had to much with the description text anyway (resulting in diffs), I also took the liberty of cleaning up a double space. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 3 + .../markdown/options/pod-id-file.container.md | 4 + docs/source/markdown/options/pod-id-file.pod.md | 3 + docs/source/markdown/podman-create.1.md.in | 4 +- docs/source/markdown/podman-pod-rm.1.md | 81 -------------------- docs/source/markdown/podman-pod-rm.1.md.in | 79 ++++++++++++++++++++ docs/source/markdown/podman-pod-start.1.md | 58 --------------- docs/source/markdown/podman-pod-start.1.md.in | 56 ++++++++++++++ docs/source/markdown/podman-pod-stop.1.md | 86 ---------------------- docs/source/markdown/podman-pod-stop.1.md.in | 84 +++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 5 +- 11 files changed, 231 insertions(+), 232 deletions(-) create mode 100644 docs/source/markdown/options/pod-id-file.container.md create mode 100644 docs/source/markdown/options/pod-id-file.pod.md delete mode 100644 docs/source/markdown/podman-pod-rm.1.md create mode 100644 docs/source/markdown/podman-pod-rm.1.md.in delete mode 100644 docs/source/markdown/podman-pod-start.1.md create mode 100644 docs/source/markdown/podman-pod-start.1.md.in delete mode 100644 docs/source/markdown/podman-pod-stop.1.md create mode 100644 docs/source/markdown/podman-pod-stop.1.md.in (limited to 'docs') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 5a30aab78..2bdcce197 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -13,6 +13,9 @@ podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-rm.1.md +podman-pod-start.1.md +podman-pod-stop.1.md podman-pull.1.md podman-push.1.md podman-rm.1.md diff --git a/docs/source/markdown/options/pod-id-file.container.md b/docs/source/markdown/options/pod-id-file.container.md new file mode 100644 index 000000000..1c102dc6b --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.container.md @@ -0,0 +1,4 @@ +#### **--pod-id-file**=*file* + +Run container in an existing pod and read the pod's ID from the specified *file*. +If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. diff --git a/docs/source/markdown/options/pod-id-file.pod.md b/docs/source/markdown/options/pod-id-file.pod.md new file mode 100644 index 000000000..69e2ac6e9 --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.pod.md @@ -0,0 +1,3 @@ +#### **--pod-id-file**=*file* + +Read pod ID from the specified *file* and <> the pod. Can be specified multiple times. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 2827964f7..b943783cb 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -476,9 +476,7 @@ Default is to create a private PID namespace for the container Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`. To make a pod with more granular options, use the `podman pod create` command before creating a container. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--privileged** diff --git a/docs/source/markdown/podman-pod-rm.1.md b/docs/source/markdown/podman-pod-rm.1.md deleted file mode 100644 index befab6791..000000000 --- a/docs/source/markdown/podman-pod-rm.1.md +++ /dev/null @@ -1,81 +0,0 @@ -% podman-pod-rm(1) - -## NAME -podman\-pod\-rm - Remove one or more stopped pods and containers - -## SYNOPSIS -**podman pod rm** [*options*] *pod* - -## DESCRIPTION -**podman pod rm** will remove one or more stopped pods and their containers from the host. The pod name or ID can be used. The \-f option stops all containers and then removes them before removing the pod. If all containers added by the user are in an exited state, the pod will be removed. - -## OPTIONS - -#### **--all**, **-a** - -Remove all pods. Can be used in conjunction with \-f as well. - -#### **--force**, **-f** - -Stop running containers and delete all stopped containers before removal of pod. - -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and remove the pod. Can be specified multiple times. - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping running containers within the pod. The --force option must be specified to use the --time option. - -## EXAMPLE - -Remove pod with a given name -``` -podman pod rm mywebserverpod -``` - -Remove multiple pods with given names and/or IDs -``` -podman pod rm mywebserverpod myflaskserverpod 860a4b23 -``` - -Forcefully remove pod with a given ID -``` -podman pod rm -f 860a4b23 -``` - -Forcefully remove all pods -``` -podman pod rm -f -a -podman pod rm -fa -``` - -Remove pod using ID specified in a given file -``` -podman pod rm --pod-id-file /path/to/id/file -``` - -## Exit Status - **0** All specified pods removed - - **1** One of the specified pods did not exist, and no other failures - - **2** One of the specified pods is attached to a container - - **125** The command fails for any other reason - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)** - -## HISTORY -July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-rm.1.md.in b/docs/source/markdown/podman-pod-rm.1.md.in new file mode 100644 index 000000000..54646ebe3 --- /dev/null +++ b/docs/source/markdown/podman-pod-rm.1.md.in @@ -0,0 +1,79 @@ +% podman-pod-rm(1) + +## NAME +podman\-pod\-rm - Remove one or more stopped pods and containers + +## SYNOPSIS +**podman pod rm** [*options*] *pod* + +## DESCRIPTION +**podman pod rm** will remove one or more stopped pods and their containers from the host. The pod name or ID can be used. The \-f option stops all containers and then removes them before removing the pod. If all containers added by the user are in an exited state, the pod will be removed. + +## OPTIONS + +#### **--all**, **-a** + +Remove all pods. Can be used in conjunction with \-f as well. + +#### **--force**, **-f** + +Stop running containers and delete all stopped containers before removal of pod. + +#### **--ignore**, **-i** + +Ignore errors when specified pods are not in the container store. A user might +have decided to manually remove a pod which would lead to a failure during the +ExecStop directive of a systemd service referencing that pod. + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping running containers within the pod. The --force option must be specified to use the --time option. + +## EXAMPLE + +Remove pod with a given name +``` +podman pod rm mywebserverpod +``` + +Remove multiple pods with given names and/or IDs +``` +podman pod rm mywebserverpod myflaskserverpod 860a4b23 +``` + +Forcefully remove pod with a given ID +``` +podman pod rm -f 860a4b23 +``` + +Forcefully remove all pods +``` +podman pod rm -f -a +podman pod rm -fa +``` + +Remove pod using ID specified in a given file +``` +podman pod rm --pod-id-file /path/to/id/file +``` + +## Exit Status + **0** All specified pods removed + + **1** One of the specified pods did not exist, and no other failures + + **2** One of the specified pods is attached to a container + + **125** The command fails for any other reason + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)** + +## HISTORY +July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-start.1.md b/docs/source/markdown/podman-pod-start.1.md deleted file mode 100644 index 45fc50c51..000000000 --- a/docs/source/markdown/podman-pod-start.1.md +++ /dev/null @@ -1,58 +0,0 @@ -% podman-pod-start(1) - -## NAME -podman\-pod\-start - Start one or more pods - -## SYNOPSIS -**podman pod start** [*options*] *pod* ... - -## DESCRIPTION -Start containers in one or more pods. You may use pod IDs or names as input. The pod must have a container attached -to be started. - -## OPTIONS - -#### **--all**, **-a** - -Starts all pods - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and start the pod. Can be specified multiple times. - -## EXAMPLE - -Start pod with a given name -``` -podman pod start mywebserverpod -``` - -Start pods with given IDs -``` -podman pod start 860a4b23 5421ab4 -``` - -Start the latest pod created by Podman -``` -podman pod start --latest -``` - -Start all pods -``` -podman pod start --all -``` - -Start pod using ID specified in a given file -``` -podman pod start --pod-id-file /path/to/id/file -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-stop(1)](podman-pod-stop.1.md)** - -## HISTORY -July 2018, Adapted from podman start man page by Peter Hunt diff --git a/docs/source/markdown/podman-pod-start.1.md.in b/docs/source/markdown/podman-pod-start.1.md.in new file mode 100644 index 000000000..6a47ce1b9 --- /dev/null +++ b/docs/source/markdown/podman-pod-start.1.md.in @@ -0,0 +1,56 @@ +% podman-pod-start(1) + +## NAME +podman\-pod\-start - Start one or more pods + +## SYNOPSIS +**podman pod start** [*options*] *pod* ... + +## DESCRIPTION +Start containers in one or more pods. You may use pod IDs or names as input. The pod must have a container attached +to be started. + +## OPTIONS + +#### **--all**, **-a** + +Starts all pods + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +## EXAMPLE + +Start pod with a given name +``` +podman pod start mywebserverpod +``` + +Start pods with given IDs +``` +podman pod start 860a4b23 5421ab4 +``` + +Start the latest pod created by Podman +``` +podman pod start --latest +``` + +Start all pods +``` +podman pod start --all +``` + +Start pod using ID specified in a given file +``` +podman pod start --pod-id-file /path/to/id/file +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-stop(1)](podman-pod-stop.1.md)** + +## HISTORY +July 2018, Adapted from podman start man page by Peter Hunt diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md deleted file mode 100644 index bded0ba7d..000000000 --- a/docs/source/markdown/podman-pod-stop.1.md +++ /dev/null @@ -1,86 +0,0 @@ -% podman-pod-stop(1) - -## NAME -podman\-pod\-stop - Stop one or more pods - -## SYNOPSIS -**podman pod stop** [*options*] *pod* ... - -## DESCRIPTION -Stop containers in one or more pods. You may use pod IDs or names as input. - -## OPTIONS - -#### **--all**, **-a** - -Stops all pods - -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and stop the pod. Can be specified multiple times. - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping the containers in the pod. - -## EXAMPLE - -Stop a pod called *mywebserverpod* -``` -$ podman pod stop mywebserverpod -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop two pods by their short IDs. -``` -$ podman pod stop 490eb 3557fb -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -``` - -Stop the most recent pod -``` -$ podman pod stop --latest -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -``` - -Stop all pods -``` -$ podman pod stop --all -19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop two pods via --pod-id-file -``` -$ podman pod stop --pod-id-file file1 --pod-id-file file2 -19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop all pods with a timeout of 1 second. -``` -$ podman pod stop -a -t 1 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-start(1)](podman-pod-start.1.md)** - -## HISTORY -July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in new file mode 100644 index 000000000..879645cd9 --- /dev/null +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -0,0 +1,84 @@ +% podman-pod-stop(1) + +## NAME +podman\-pod\-stop - Stop one or more pods + +## SYNOPSIS +**podman pod stop** [*options*] *pod* ... + +## DESCRIPTION +Stop containers in one or more pods. You may use pod IDs or names as input. + +## OPTIONS + +#### **--all**, **-a** + +Stops all pods + +#### **--ignore**, **-i** + +Ignore errors when specified pods are not in the container store. A user might +have decided to manually remove a pod which would lead to a failure during the +ExecStop directive of a systemd service referencing that pod. + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping the containers in the pod. + +## EXAMPLE + +Stop a pod called *mywebserverpod* +``` +$ podman pod stop mywebserverpod +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop two pods by their short IDs. +``` +$ podman pod stop 490eb 3557fb +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop the most recent pod +``` +$ podman pod stop --latest +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop all pods +``` +$ podman pod stop --all +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop two pods via --pod-id-file +``` +$ podman pod stop --pod-id-file file1 --pod-id-file file2 +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop all pods with a timeout of 1 second. +``` +$ podman pod stop -a -t 1 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-start(1)](podman-pod-start.1.md)** + +## HISTORY +July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index cdfa9366a..077ad7a4a 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -496,10 +496,7 @@ Run container in an existing pod. If you want Podman to make the pod for you, pr To make a pod with more granular options, use the **podman pod create** command before creating a container. If a container is run with a pod, and the pod has an infra-container, the infra-container will be started before the container is. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. -If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--preserve-fds**=*N* -- cgit v1.2.3-54-g00ecf From 64339d47c105373557248d45fddf7ab2db435180 Mon Sep 17 00:00:00 2001 From: Toshiki Sonoda Date: Tue, 23 Aug 2022 11:54:31 +0900 Subject: Warning messages are printed and ignored if we use an unsupported option When an unsupported limit on cgroups V1 rootless systems is requested, podman prints an warning message and ignores the option/flag. ``` Target options/flags: --cpu-period, --cpu-quota, --cpu-rt-period, --cpu-rt-runtime, --cpus, --cpu-shares, --cpuset-cpus, --cpuset-mems, --memory, --memory-reservation, --memory-swap, --memory-swappiness, --blkio-weight, --device-read-bps, --device-write-bps, --device-read-iops, --device-write-iops, --blkio-weight-device ``` Related to https://github.com/containers/podman/discussions/10152 Signed-off-by: Toshiki Sonoda --- docs/source/markdown/options/blkio-weight.md | 2 ++ docs/source/markdown/options/cpu-period.md | 2 ++ docs/source/markdown/options/cpu-quota.md | 2 ++ docs/source/markdown/options/cpu-rt-period.md | 2 +- docs/source/markdown/options/cpu-rt-runtime.md | 2 +- docs/source/markdown/options/cpu-shares.md | 2 ++ docs/source/markdown/options/cpuset-cpus.md | 2 ++ docs/source/markdown/options/cpuset-mems.md | 2 ++ docs/source/markdown/options/memory-swappiness.md | 2 +- docs/source/markdown/podman-container-clone.1.md.in | 12 ++++++++++++ docs/source/markdown/podman-create.1.md.in | 16 ++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 16 ++++++++++++++++ pkg/specgen/generate/validate.go | 6 ++++++ test/e2e/container_clone_test.go | 1 + test/e2e/create_test.go | 2 ++ test/e2e/generate_kube_test.go | 2 ++ test/e2e/generate_spec_test.go | 2 ++ test/system/030-run.bats | 7 ++++++- 18 files changed, 78 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/options/blkio-weight.md b/docs/source/markdown/options/blkio-weight.md index eb8e94144..04a1071c0 100644 --- a/docs/source/markdown/options/blkio-weight.md +++ b/docs/source/markdown/options/blkio-weight.md @@ -1,3 +1,5 @@ #### **--blkio-weight**=*weight* Block IO relative weight. The _weight_ is a value between **10** and **1000**. + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md index efbe6c2ab..5c5eb56e7 100644 --- a/docs/source/markdown/options/cpu-period.md +++ b/docs/source/markdown/options/cpu-period.md @@ -8,3 +8,5 @@ microseconds. On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-quota.md b/docs/source/markdown/options/cpu-quota.md index 753797bad..81d5db3d2 100644 --- a/docs/source/markdown/options/cpu-quota.md +++ b/docs/source/markdown/options/cpu-quota.md @@ -10,3 +10,5 @@ ends (controllable via **--cpu-period**). On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-rt-period.md b/docs/source/markdown/options/cpu-rt-period.md index 9014beb33..36e88632e 100644 --- a/docs/source/markdown/options/cpu-rt-period.md +++ b/docs/source/markdown/options/cpu-rt-period.md @@ -4,4 +4,4 @@ Limit the CPU real-time period in microseconds. Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. -This option is not supported on cgroups V2 systems. +This option is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/options/cpu-rt-runtime.md b/docs/source/markdown/options/cpu-rt-runtime.md index 05b1d3b96..64f0ec38b 100644 --- a/docs/source/markdown/options/cpu-rt-runtime.md +++ b/docs/source/markdown/options/cpu-rt-runtime.md @@ -7,4 +7,4 @@ Period of 1,000,000us and Runtime of 950,000us means that this container could c The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. -This option is not supported on cgroups V2 systems. +This option is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md index c2115c1bf..c0e2c3035 100644 --- a/docs/source/markdown/options/cpu-shares.md +++ b/docs/source/markdown/options/cpu-shares.md @@ -37,3 +37,5 @@ this can result in the following division of CPU shares: On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpuset-cpus.md b/docs/source/markdown/options/cpuset-cpus.md index a67766897..8a2a82e9f 100644 --- a/docs/source/markdown/options/cpuset-cpus.md +++ b/docs/source/markdown/options/cpuset-cpus.md @@ -7,3 +7,5 @@ CPUs in which to allow execution. Can be specified as a comma-separated list On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpuset-mems.md b/docs/source/markdown/options/cpuset-mems.md index 1eeab7b13..b86d0ef6b 100644 --- a/docs/source/markdown/options/cpuset-mems.md +++ b/docs/source/markdown/options/cpuset-mems.md @@ -10,3 +10,5 @@ two memory nodes. On some systems, changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/memory-swappiness.md b/docs/source/markdown/options/memory-swappiness.md index 65f0ef310..1e6a51188 100644 --- a/docs/source/markdown/options/memory-swappiness.md +++ b/docs/source/markdown/options/memory-swappiness.md @@ -2,4 +2,4 @@ Tune a container's memory swappiness behavior. Accepts an integer between *0* and *100*. -This flag is not supported on cgroups V2 systems. +This flag is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in index cf760d7a2..26f414b62 100644 --- a/docs/source/markdown/podman-container-clone.1.md.in +++ b/docs/source/markdown/podman-container-clone.1.md.in @@ -40,6 +40,8 @@ Set a number of CPUs for the container that overrides the original containers CP This is shorthand for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set. +This option is not supported on cgroups V1 rootless systems. + @@option cpuset-cpus If none are specified, the original container's CPUset is used. @@ -54,10 +56,14 @@ If none are specified, the original container's CPU memory nodes are used. Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path* Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--force**, **-f** Force removal of the original container that we are cloning. Can only be used in conjunction with **--destroy**. @@ -74,6 +80,8 @@ system's page size (the value would be very large, that's millions of trillions) If no memory limits are specified, the original container's will be used. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*limit* Memory soft limit (format: `[]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) @@ -84,6 +92,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit from the container being cloned. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*limit* A limit value equal to memory plus swap. Must be used with the **-m** @@ -95,6 +105,8 @@ The format of `LIMIT` is `[]`. Unit can be `b` (bytes), `k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness #### **--name** diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 7ec4fc66f..74348ac7d 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -131,6 +131,8 @@ On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +This option is not supported on cgroups V1 rootless systems. + @@option cpuset-cpus @@option cpuset-mems @@ -165,18 +167,26 @@ Add a rule to the cgroup allowed devices list. The rule is expected to be in the Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--device-read-iops**=*path* Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path* Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-iops**=*path* Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000) +This option is not supported on cgroups V1 rootless systems. + #### **--disable-content-trust** This is a Docker specific option to disable image verification to a Docker @@ -366,6 +376,8 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of trillions). +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*limit* Memory soft limit (format: `[]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) @@ -376,6 +388,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*limit* A limit value equal to memory plus swap. Must be used with the **-m** @@ -387,6 +401,8 @@ The format of `LIMIT` is `[]`. Unit can be `b` (bytes), `k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness @@option mount diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index d10520e35..e943ec005 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -146,6 +146,8 @@ On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +This option is not supported on cgroups V1 rootless systems. + @@option cpuset-cpus @@option cpuset-mems @@ -196,18 +198,26 @@ Add a rule to the cgroup allowed devices list Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-read-iops**=*path:rate* Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path:rate* Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-iops**=*path:rate* Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). +This option is not supported on cgroups V1 rootless systems. + #### **--disable-content-trust** This is a Docker specific option to disable image verification to a Docker @@ -377,6 +387,8 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of trillions). +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*number[unit]* Memory soft limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). @@ -387,6 +399,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*number[unit]* A limit value equal to memory plus swap. @@ -399,6 +413,8 @@ the value of **--memory**. Set _number_ to **-1** to enable unlimited swap. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness @@option mount diff --git a/pkg/specgen/generate/validate.go b/pkg/specgen/generate/validate.go index 9c933d747..3c5d5fb96 100644 --- a/pkg/specgen/generate/validate.go +++ b/pkg/specgen/generate/validate.go @@ -9,6 +9,7 @@ import ( "github.com/containers/common/pkg/cgroups" "github.com/containers/common/pkg/sysinfo" + "github.com/containers/podman/v4/pkg/rootless" "github.com/containers/podman/v4/pkg/specgen" "github.com/containers/podman/v4/utils" ) @@ -19,6 +20,11 @@ func verifyContainerResourcesCgroupV1(s *specgen.SpecGenerator) ([]string, error sysInfo := sysinfo.New(true) + if s.ResourceLimits != nil && rootless.IsRootless() { + s.ResourceLimits = nil + warnings = append(warnings, "Resource limits are not supported and ignored on cgroups V1 rootless systems") + } + if s.ResourceLimits == nil { return warnings, nil } diff --git a/test/e2e/container_clone_test.go b/test/e2e/container_clone_test.go index 94ccd6ffe..d7641e42a 100644 --- a/test/e2e/container_clone_test.go +++ b/test/e2e/container_clone_test.go @@ -87,6 +87,7 @@ var _ = Describe("Podman container clone", func() { }) It("podman container clone resource limits override", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") create := podmanTest.Podman([]string{"create", "--cpus=5", ALPINE}) create.WaitWithDefaultTimeout() Expect(create).To(Exit(0)) diff --git a/test/e2e/create_test.go b/test/e2e/create_test.go index 9679aad24..b35d0f3c5 100644 --- a/test/e2e/create_test.go +++ b/test/e2e/create_test.go @@ -438,6 +438,7 @@ var _ = Describe("Podman create", func() { }) It("podman create with -m 1000000 sets swap to 2000000", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") numMem := 1000000 ctrName := "testCtr" session := podmanTest.Podman([]string{"create", "-t", "-m", fmt.Sprintf("%db", numMem), "--name", ctrName, ALPINE, "/bin/sh"}) @@ -452,6 +453,7 @@ var _ = Describe("Podman create", func() { }) It("podman create --cpus 5 sets nanocpus", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") numCpus := 5 nanoCPUs := numCpus * 1000000000 ctrName := "testCtr" diff --git a/test/e2e/generate_kube_test.go b/test/e2e/generate_kube_test.go index 142f32d19..e7ceaf2d2 100644 --- a/test/e2e/generate_kube_test.go +++ b/test/e2e/generate_kube_test.go @@ -490,6 +490,7 @@ var _ = Describe("Podman generate kube", func() { }) It("podman generate kube on pod with memory limit", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") podName := "testMemoryLimit" podSession := podmanTest.Podman([]string{"pod", "create", "--name", podName}) podSession.WaitWithDefaultTimeout() @@ -515,6 +516,7 @@ var _ = Describe("Podman generate kube", func() { }) It("podman generate kube on pod with cpu limit", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") podName := "testCpuLimit" podSession := podmanTest.Podman([]string{"pod", "create", "--name", podName}) podSession.WaitWithDefaultTimeout() diff --git a/test/e2e/generate_spec_test.go b/test/e2e/generate_spec_test.go index 57cd9546b..9188b5222 100644 --- a/test/e2e/generate_spec_test.go +++ b/test/e2e/generate_spec_test.go @@ -41,6 +41,7 @@ var _ = Describe("Podman generate spec", func() { }) It("podman generate spec basic usage", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") session := podmanTest.Podman([]string{"create", "--cpus", "5", "--name", "specgen", ALPINE}) session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) @@ -51,6 +52,7 @@ var _ = Describe("Podman generate spec", func() { }) It("podman generate spec file", func() { + SkipIfRootlessCgroupsV1("Not supported for rootless + CgroupsV1") session := podmanTest.Podman([]string{"create", "--cpus", "5", "--name", "specgen", ALPINE}) session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) diff --git a/test/system/030-run.bats b/test/system/030-run.bats index 908c169ee..a3bfe5780 100644 --- a/test/system/030-run.bats +++ b/test/system/030-run.bats @@ -56,7 +56,12 @@ echo $rand | 0 | $rand @test "podman run --memory=0 runtime option" { run_podman run --memory=0 --rm $IMAGE echo hello - is "$output" "hello" "failed to run when --memory is set to 0" + if is_rootless && ! is_cgroupsv2; then + is "${lines[0]}" "Resource limits are not supported and ignored on cgroups V1 rootless systems" "--memory is not supported" + is "${lines[1]}" "hello" "--memory is ignored" + else + is "$output" "hello" "failed to run when --memory is set to 0" + fi } # 'run --preserve-fds' passes a number of additional file descriptors into the container -- cgit v1.2.3-54-g00ecf From 5b06b2e77b07f35e489e307e296f26016cd4aa0c Mon Sep 17 00:00:00 2001 From: Tomas Volf Date: Tue, 23 Aug 2022 13:45:15 +0200 Subject: Document restrictions on transport in FROM When using remote podman client, not all transports work as expected. So document this limitation. Fixes: containers/podman#15141 Signed-off-by: Tomas Volf --- docs/source/markdown/podman-build.1.md.in | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index dab705f94..209458181 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -297,6 +297,12 @@ environment variable. `export BUILDAH_FORMAT=docker` Overrides the first `FROM` instruction within the Containerfile. If there are multiple FROM instructions in a Containerfile, only the first is changed. +With the remote podman client, not all container transports will work as +expected. For example, oci-archive:/x.tar will reference /x.tar on the remote +machine instead of on the client. If you need to support remote podman clients, +it is best to restrict yourself to containers-storage: and docker:// +transports. + #### **--help**, **-h** Print usage statement -- cgit v1.2.3-54-g00ecf From 5f719b533ec6468911a284f2d901d65c098f4539 Mon Sep 17 00:00:00 2001 From: Niall Crowe Date: Tue, 16 Aug 2022 15:38:59 +0100 Subject: podman kube play/down --read from URL `podman kube play` can create pods and containers from YAML read from a URL poiniting to a YAML file. For example: `podman kube play https://example.com/demo.yml`. `podman kube down` can also teardown pods and containers created from that YAML file by also reading YAML from a URL, provided the YAML file the URL points to has not been changed or altered since it was used to create pods and containers Closes #14955 Signed-off-by: Niall Crowe --- cmd/podman/kube/down.go | 3 ++- cmd/podman/kube/play.go | 26 +++++++++++++++++++++++--- docs/source/markdown/podman-kube-down.1.md | 27 ++++++++++++++++++++++++--- docs/source/markdown/podman-kube-play.1.md.in | 20 ++++++++++++++++++-- test/system/700-play.bats | 25 +++++++++++++++++++++++++ 5 files changed, 92 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/cmd/podman/kube/down.go b/cmd/podman/kube/down.go index a670d911c..792c80499 100644 --- a/cmd/podman/kube/down.go +++ b/cmd/podman/kube/down.go @@ -19,7 +19,8 @@ var ( Args: cobra.ExactArgs(1), ValidArgsFunction: common.AutocompleteDefaultOneArg, Example: `podman kube down nginx.yml - cat nginx.yml | podman kube down -`, + cat nginx.yml | podman kube down - + podman kube down https://example.com/nginx.yml`, } ) diff --git a/cmd/podman/kube/play.go b/cmd/podman/kube/play.go index d7719e28e..c846ec32c 100644 --- a/cmd/podman/kube/play.go +++ b/cmd/podman/kube/play.go @@ -5,7 +5,9 @@ import ( "errors" "fmt" "io" + "io/ioutil" "net" + "net/http" "os" "strings" @@ -13,6 +15,7 @@ import ( "github.com/containers/common/pkg/completion" "github.com/containers/image/v5/types" "github.com/containers/podman/v4/cmd/podman/common" + "github.com/containers/podman/v4/cmd/podman/parse" "github.com/containers/podman/v4/cmd/podman/registry" "github.com/containers/podman/v4/cmd/podman/utils" "github.com/containers/podman/v4/libpod/define" @@ -52,7 +55,8 @@ var ( ValidArgsFunction: common.AutocompleteDefaultOneArg, Example: `podman kube play nginx.yml cat nginx.yml | podman kube play - - podman kube play --creds user:password --seccomp-profile-root /custom/path apache.yml`, + podman kube play --creds user:password --seccomp-profile-root /custom/path apache.yml + podman kube play https://example.com/nginx.yml`, } ) @@ -67,7 +71,8 @@ var ( ValidArgsFunction: common.AutocompleteDefaultOneArg, Example: `podman play kube nginx.yml cat nginx.yml | podman play kube - - podman play kube --creds user:password --seccomp-profile-root /custom/path apache.yml`, + podman play kube --creds user:password --seccomp-profile-root /custom/path apache.yml + podman play kube https://example.com/nginx.yml`, } ) @@ -167,7 +172,7 @@ func playFlags(cmd *cobra.Command) { _ = cmd.RegisterFlagCompletionFunc(contextDirFlagName, completion.AutocompleteDefault) // NOTE: The service-container flag is marked as hidden as it - // is purely designed for running kube-play in systemd units. + // is purely designed for running kube-play or play-kube in systemd units. // It is not something users should need to know or care about. // // Having a flag rather than an env variable is cleaner. @@ -255,6 +260,7 @@ func play(cmd *cobra.Command, args []string) error { return err } } + return kubeplay(reader) } @@ -263,6 +269,7 @@ func playKube(cmd *cobra.Command, args []string) error { } func readerFromArg(fileName string) (*bytes.Reader, error) { + errURL := parse.ValidURL(fileName) if fileName == "-" { // Read from stdin data, err := io.ReadAll(os.Stdin) if err != nil { @@ -270,6 +277,19 @@ func readerFromArg(fileName string) (*bytes.Reader, error) { } return bytes.NewReader(data), nil } + if errURL == nil { + response, err := http.Get(fileName) + if err != nil { + return nil, err + } + defer response.Body.Close() + + data, err := ioutil.ReadAll(response.Body) + if err != nil { + return nil, err + } + return bytes.NewReader(data), nil + } f, err := os.Open(fileName) if err != nil { return nil, err diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md index 92abd4ba3..c345abbd1 100644 --- a/docs/source/markdown/podman-kube-down.1.md +++ b/docs/source/markdown/podman-kube-down.1.md @@ -4,10 +4,14 @@ podman-kube-down - Remove containers and pods based on Kubernetes YAML ## SYNOPSIS -**podman kube down** *file.yml|-* +**podman kube down** *file.yml|-|https://website.io/file.yml* ## DESCRIPTION -**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the YAML from stdin. +**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML +file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the +YAML from stdin. The input can also be a URL that points to a YAML file such as https://podman.io/demo.yml. `podman kube down` will then teardown the pods and +containers created by `podman kube play` via the same Kubernetes YAML from the URL. However, `podman kube down` will not work with a URL if the YAML file the URL +points to has been changed or altered since the creation of the pods and containers using `podman kube play`. ## EXAMPLES @@ -30,14 +34,31 @@ spec: Remove the pod and containers as described in the `demo.yml` file ``` $ podman kube down demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` -Remove the pod and containers as described in the`demo.yml` file YAML sent to stdin +Remove the pod and containers as described in the `demo.yml` file YAML sent to stdin ``` $ cat demo.yml | podman kube play - +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +Remove the pods and containers as described in the `demo.yml` file YAML read from a URL +``` +$ podman kube down https://podman.io/demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` +`podman kube down` will not work with a URL if the YAML file the URL points to has been changed +or altered since it was used to create the pods and containers. ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 1b9544fb6..f0b404057 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -4,13 +4,14 @@ podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML ## SYNOPSIS -**podman kube play** [*options*] *file.yml|-* +**podman kube play** [*options*] *file.yml|-|https://website.io/file.yml* ## DESCRIPTION **podman kube play** will read in a structured file of Kubernetes YAML. It will then recreate the containers, pods or volumes described in the YAML. Containers within a pod are then started and the ID of the new Pod or the name of the new Volume is output. If the yaml file is specified as "-" then `podman kube play` will read the YAML file from stdin. Using the `--down` command line option, it is also capable of tearing down the pods created by a previous run of `podman kube play`. Using the `--replace` command line option, it will tear down the pods(if any) created by a previous run of `podman kube play` and recreate the pods with the Kubernetes YAML file. Ideally the input file would be one created by Podman (see podman-kube-generate(1)). This would guarantee a smooth import and expected results. +The input can also be a URL that points to a YAML file such as https://podman.io/demo.yml. `podman kube play` will read the YAML from the URL and create pods and containers from it. Currently, the supported Kubernetes kinds are: - Pod @@ -300,8 +301,23 @@ Create a pod connected to two networks (called net1 and net2) with a static ip $ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` - Please take into account that networks must be created first using podman-network-create(1). +Create and teardown from a URL pointing to a YAML file +``` +$ podman kube play https://podman.io/demo.yml +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 + +$ podman kube play --down https://podman.io/demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` +`podman kube play --down` will not work with a URL if the YAML file the URL points to +has been changed or altered. + + + ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/test/system/700-play.bats b/test/system/700-play.bats index e1955cfd1..bad9544ff 100644 --- a/test/system/700-play.bats +++ b/test/system/700-play.bats @@ -361,3 +361,28 @@ status: {} run_podman pod rm -a run_podman rm -a } + +@test "podman kube play - URL" { + TESTDIR=$PODMAN_TMPDIR/testdir + mkdir -p $TESTDIR + echo "$testYaml" | sed "s|TESTDIR|${TESTDIR}|g" > $PODMAN_TMPDIR/test.yaml + + HOST_PORT=$(random_free_port) + SERVER=http://127.0.0.1:$HOST_PORT + + run_podman run -d --name myyaml -p "$HOST_PORT:80" \ + -v $PODMAN_TMPDIR/test.yaml:/var/www/testpod.yaml:Z \ + -w /var/www \ + $IMAGE /bin/busybox-extras httpd -f -p 80 + + run_podman kube play $SERVER/testpod.yaml + run_podman inspect test_pod-test --format "{{.State.Running}}" + is "$output" "true" + run_podman kube down $SERVER/testpod.yaml + run_podman 125 inspect test_pod-test + is "$output" ".*Error: inspecting object: no such object: \"test_pod-test\"" + + run_podman pod rm -a -f + run_podman rm -a -f + run_podman rm -f -t0 myyaml +} -- cgit v1.2.3-54-g00ecf From 5c9bac141ecdf7a87d40e0c0aba1d49893f24474 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 19:10:42 -0600 Subject: Man pages: refactor common options: --cpus Only on podman create and run: the --cpus option on container-clone and pod-clone can probably be combined, but maybe later. pod-create has unique wording that can't be combined. This is a freebie to review: the text in both files was already identical, and I made no changes to it. hack/markdown-preprocess-review will agree, and show you no diffs, because there are none worth seeing. Signed-off-by: Ed Santiago --- docs/source/markdown/options/cpus.container.md | 11 +++++++++++ docs/source/markdown/podman-create.1.md.in | 12 +----------- docs/source/markdown/podman-run.1.md.in | 12 +----------- 3 files changed, 13 insertions(+), 22 deletions(-) create mode 100644 docs/source/markdown/options/cpus.container.md (limited to 'docs') diff --git a/docs/source/markdown/options/cpus.container.md b/docs/source/markdown/options/cpus.container.md new file mode 100644 index 000000000..63f243e11 --- /dev/null +++ b/docs/source/markdown/options/cpus.container.md @@ -0,0 +1,11 @@ +#### **--cpus**=*number* + +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 2fecdb256..3ae558996 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -119,17 +119,7 @@ Block IO relative device weight. @@option cpu-shares -#### **--cpus**=*number* - -Number of CPUs. The default is *0.0* which means no limit. This is shorthand -for **--cpu-period** and **--cpu-quota**, so you may only set either -**--cpus** or **--cpu-period** and **--cpu-quota**. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error - -This option is not supported on cgroups V1 rootless systems. +@@option cpus.container @@option cpuset-cpus diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 40e05c06c..4fae69241 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -134,17 +134,7 @@ each of **stdin**, **stdout**, and **stderr**. @@option cpu-shares -#### **--cpus**=*number* - -Number of CPUs. The default is *0.0* which means no limit. This is shorthand -for **--cpu-period** and **--cpu-quota**, so you may only set either -**--cpus** or **--cpu-period** and **--cpu-quota**. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error - -This option is not supported on cgroups V1 rootless systems. +@@option cpus.container @@option cpuset-cpus -- cgit v1.2.3-54-g00ecf From 2c03681b2c04c28add7b0d8eafbfce37937ce653 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 19:23:54 -0600 Subject: Man pages: refactor common options: --disable-content-trust A NOP option. I chose the container word, of course, and the word 'option' instead of 'flag'. I also hyphenated where needed. I'm choosing to eliminate the "not on remote" text, because I don't think it's true: podman-remote happily accepts that flag on all those commands, including build. (It's marked as hidden on build, but still accepted). Signed-off-by: Ed Santiago --- docs/source/markdown/options/disable-content-trust.md | 5 +++++ docs/source/markdown/podman-build.1.md.in | 6 +----- docs/source/markdown/podman-create.1.md.in | 6 +----- docs/source/markdown/podman-pull.1.md.in | 6 +----- docs/source/markdown/podman-push.1.md.in | 6 +----- docs/source/markdown/podman-run.1.md.in | 6 +----- 6 files changed, 10 insertions(+), 25 deletions(-) create mode 100644 docs/source/markdown/options/disable-content-trust.md (limited to 'docs') diff --git a/docs/source/markdown/options/disable-content-trust.md b/docs/source/markdown/options/disable-content-trust.md new file mode 100644 index 000000000..a2d1d8ad7 --- /dev/null +++ b/docs/source/markdown/options/disable-content-trust.md @@ -0,0 +1,5 @@ +#### **--disable-content-trust** + +This is a Docker-specific option to disable image verification to a container +registry and is not supported by Podman. This option is a NOOP and provided +solely for scripting compatibility. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index dab705f94..87a21a7ae 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -230,11 +230,7 @@ registries, and images being written to local storage would only need to be decompressed again to be stored. Compression can be forced in all cases by specifying **--disable-compression=false**. -#### **--disable-content-trust** - -This is a Docker specific option to disable image verification to a container -registry and is not supported by Podman. This option is a NOOP and provided -solely for scripting compatibility. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +@@option disable-content-trust #### **--dns**=*dns* diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 3ae558996..c83083674 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -175,11 +175,7 @@ Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda: This option is not supported on cgroups V1 rootless systems. -#### **--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. +@@option disable-content-trust #### **--dns**=*dns* diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index db041298e..03f9b8fd7 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -57,11 +57,7 @@ All tagged images in the repository will be pulled. @@option creds -#### **--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. +@@option disable-content-trust #### **--help**, **-h** diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index b7d05d988..a98964e45 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -66,11 +66,7 @@ Specifies the compression format to use. Supported values are: `gzip`, `zstd` a 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. +@@option disable-content-trust #### **--format**, **-f**=*format* diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 4fae69241..7fb7a455b 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -206,11 +206,7 @@ Limit write rate (in IO operations per second) to a device (e.g. **--device-writ This option is not supported on cgroups V1 rootless systems. -#### **--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. +@@option disable-content-trust #### **--dns**=*ipaddr* -- cgit v1.2.3-54-g00ecf From 7d7aead51197fa98bb223b9e90b75ac4cd7cdf0a Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 10:25:04 -0600 Subject: Man pages: refactor common options: --device-cgroup-rule I chose the version from podman-create. (This is unusual. podman-run tends to have the better-maintained, more up-to-date version.) Signed-off-by: Ed Santiago --- docs/source/markdown/options/device-cgroup-rule.md | 6 ++++++ docs/source/markdown/podman-create.1.md.in | 7 +------ docs/source/markdown/podman-run.1.md.in | 4 +--- 3 files changed, 8 insertions(+), 9 deletions(-) create mode 100644 docs/source/markdown/options/device-cgroup-rule.md (limited to 'docs') diff --git a/docs/source/markdown/options/device-cgroup-rule.md b/docs/source/markdown/options/device-cgroup-rule.md new file mode 100644 index 000000000..0ba3d4668 --- /dev/null +++ b/docs/source/markdown/options/device-cgroup-rule.md @@ -0,0 +1,6 @@ +#### **--device-cgroup-rule**=*"type major:minor mode"* + +Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt): + - type: a (all), c (char), or b (block); + - major and minor: either a number, or * for all; + - mode: a composition of r (read), w (write), and m (mknod(2)). diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index c83083674..9518568bb 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -144,12 +144,7 @@ Podman may load kernel modules required for using the specified device. The devices that podman will load modules when necessary are: /dev/fuse. -#### **--device-cgroup-rule**=*"type major:minor mode"* - -Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt): - - type: a (all), c (char), or b (block); - - major and minor: either a number, or * for all; - - mode: a composition of r (read), w (write), and m (mknod(2)). +@@option device-cgroup-rule #### **--device-read-bps**=*path* diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 7fb7a455b..3e31ccc45 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -178,9 +178,7 @@ Podman may load kernel modules required for using the specified device. The devices that Podman will load modules when necessary are: /dev/fuse. -#### **--device-cgroup-rule**=*rule* - -Add a rule to the cgroup allowed devices list +@@option device-cgroup-rule #### **--device-read-bps**=*path:rate* -- cgit v1.2.3-54-g00ecf From 8b1e88bf80b3cd650be04fd397f7b85d355788dd Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Tue, 23 Aug 2022 16:12:06 -0400 Subject: Fix documentation of use of tcp connections Fixes: https://github.com/containers/podman/issues/15430 Signed-off-by: Daniel J Walsh --- docs/source/markdown/podman-system-service.1.md | 2 +- test/apiv2/python/rest_api/fixtures/api_testcase.py | 2 +- test/apiv2/python/rest_api/v1_test_rest_v1_0_0.py | 2 +- test/system/272-system-connection.bats | 4 ++-- test/system/900-ssh.bats | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 99fde8ce4..3e7a00362 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -8,7 +8,7 @@ podman\-system\-service - Run an API service ## DESCRIPTION The **podman system service** command creates a listening service that will answer API calls for Podman. You may -optionally provide an endpoint for the API in URI form. For example, *unix:///tmp/foobar.sock* or *tcp:localhost:8080*. +optionally provide an endpoint for the API in URI form. For example, *unix:///tmp/foobar.sock* or *tcp://localhost:8080*. If no endpoint is provided, defaults will be used. The default endpoint for a rootful service is *unix:///run/podman/podman.sock* and rootless is *unix://$XDG_RUNTIME_DIR/podman/podman.sock* (for example *unix:///run/user/1000/podman/podman.sock*) diff --git a/test/apiv2/python/rest_api/fixtures/api_testcase.py b/test/apiv2/python/rest_api/fixtures/api_testcase.py index f47136555..edb34b31e 100644 --- a/test/apiv2/python/rest_api/fixtures/api_testcase.py +++ b/test/apiv2/python/rest_api/fixtures/api_testcase.py @@ -20,7 +20,7 @@ class APITestCase(unittest.TestCase): APITestCase.podman = Podman() APITestCase.service = APITestCase.podman.open( - "system", "service", "tcp:localhost:8080", "--time=0" + "system", "service", "tcp://localhost:8080", "--time=0" ) # give the service some time to be ready... time.sleep(2) diff --git a/test/apiv2/python/rest_api/v1_test_rest_v1_0_0.py b/test/apiv2/python/rest_api/v1_test_rest_v1_0_0.py index 905c29683..2274f25bf 100644 --- a/test/apiv2/python/rest_api/v1_test_rest_v1_0_0.py +++ b/test/apiv2/python/rest_api/v1_test_rest_v1_0_0.py @@ -63,7 +63,7 @@ class TestApi(unittest.TestCase): podman(), "system", "service", - "tcp:localhost:8080", + "tcp://localhost:8080", "--log-level=debug", "--time=0", ], diff --git a/test/system/272-system-connection.bats b/test/system/272-system-connection.bats index e9e9a01ea..e937a7273 100644 --- a/test/system/272-system-connection.bats +++ b/test/system/272-system-connection.bats @@ -95,12 +95,12 @@ $c2[ ]\+tcp://localhost:54321[ ]\+true" \ # we need for the server. ${PODMAN%%-remote*} --root ${PODMAN_TMPDIR}/root \ --runroot ${PODMAN_TMPDIR}/runroot \ - system service -t 99 tcp:localhost:$_SERVICE_PORT & + system service -t 99 tcp://localhost:$_SERVICE_PORT & _SERVICE_PID=$! wait_for_port localhost $_SERVICE_PORT _run_podman_remote info --format '{{.Host.RemoteSocket.Path}}' - is "$output" "tcp:localhost:$_SERVICE_PORT" \ + is "$output" "tcp://localhost:$_SERVICE_PORT" \ "podman info works, and talks to the correct server" _run_podman_remote info --format '{{.Store.GraphRoot}}' diff --git a/test/system/900-ssh.bats b/test/system/900-ssh.bats index 0757f5838..4f1682d48 100644 --- a/test/system/900-ssh.bats +++ b/test/system/900-ssh.bats @@ -46,7 +46,7 @@ function _run_podman_remote() { ${PODMAN%%-remote*} --root ${PODMAN_TMPDIR}/root \ --runroot ${PODMAN_TMPDIR}/runroot \ - system service -t 99 tcp:localhost:$_SERVICE_PORT & + system service -t 99 tcp://localhost:$_SERVICE_PORT & _SERVICE_PID=$! wait_for_port localhost $_SERVICE_PORT -- cgit v1.2.3-54-g00ecf From 9dca68bdd9e9b2dc05554e6bfa3502cea4c3762c Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 09:42:15 -0600 Subject: Man pages: refactor common options: --ignore Should be an easy one to review. Signed-off-by: Ed Santiago --- docs/source/markdown/options/ignore.md | 5 +++++ docs/source/markdown/podman-pod-rm.1.md.in | 6 +----- docs/source/markdown/podman-pod-stop.1.md.in | 6 +----- docs/source/markdown/podman-rm.1.md.in | 6 +----- docs/source/markdown/podman-stop.1.md.in | 6 +----- 5 files changed, 9 insertions(+), 20 deletions(-) create mode 100644 docs/source/markdown/options/ignore.md (limited to 'docs') diff --git a/docs/source/markdown/options/ignore.md b/docs/source/markdown/options/ignore.md new file mode 100644 index 000000000..231d75957 --- /dev/null +++ b/docs/source/markdown/options/ignore.md @@ -0,0 +1,5 @@ +#### **--ignore**, **-i** + +Ignore errors when specified <> are not in the container store. A user +might have decided to manually remove a <> which would lead to a failure +during the ExecStop directive of a systemd service referencing that <>. diff --git a/docs/source/markdown/podman-pod-rm.1.md.in b/docs/source/markdown/podman-pod-rm.1.md.in index 54646ebe3..82e28acb1 100644 --- a/docs/source/markdown/podman-pod-rm.1.md.in +++ b/docs/source/markdown/podman-pod-rm.1.md.in @@ -19,11 +19,7 @@ Remove all pods. Can be used in conjunction with \-f as well. Stop running containers and delete all stopped containers before removal of pod. -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. +@@option ignore #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in index 879645cd9..3655c3938 100644 --- a/docs/source/markdown/podman-pod-stop.1.md.in +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -15,11 +15,7 @@ Stop containers in one or more pods. You may use pod IDs or names as input. Stops all pods -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. +@@option ignore #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in index fa3031b29..c0fa94d82 100644 --- a/docs/source/markdown/podman-rm.1.md.in +++ b/docs/source/markdown/podman-rm.1.md.in @@ -56,11 +56,7 @@ Containers could have been created by a different container engine. In addition, forcing can be used to remove unusable containers, e.g. containers whose OCI runtime has become unavailable. -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. +@@option ignore #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-stop.1.md.in b/docs/source/markdown/podman-stop.1.md.in index 04fc9387f..9aaccdfaa 100644 --- a/docs/source/markdown/podman-stop.1.md.in +++ b/docs/source/markdown/podman-stop.1.md.in @@ -47,11 +47,7 @@ Valid filters are listed below: | pod | [Pod] name or full or partial ID of pod | | network | [Network] name or full ID of network | -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. +@@option ignore #### **--latest**, **-l** -- cgit v1.2.3-54-g00ecf From b4584ea8546be227c74174130ec3a04a93996d28 Mon Sep 17 00:00:00 2001 From: Aditya R Date: Wed, 24 Aug 2022 11:22:33 +0530 Subject: run,create: add support for --env-merge for preprocessing vars Allow end users to preprocess default environment variables before injecting them into container using `--env-merge` Usage ``` podman run -it --rm --env-merge some=${some}-edit --env-merge some2=${some2}-edit2 myimage sh ``` Closes: https://github.com/containers/podman/issues/15288 Signed-off-by: Aditya R --- cmd/podman/common/create.go | 8 ++++++++ docs/source/markdown/options/env-merge.md | 5 +++++ docs/source/markdown/podman-create.1.md.in | 2 ++ docs/source/markdown/podman-run.1.md.in | 2 ++ go.mod | 1 + pkg/api/handlers/compat/containers_create.go | 1 + pkg/api/handlers/types.go | 1 + pkg/domain/entities/pods.go | 1 + pkg/specgen/generate/container.go | 12 ++++++++++++ pkg/specgen/specgen.go | 3 +++ pkg/specgenutil/specgen.go | 3 +++ test/e2e/run_env_test.go | 11 +++++++++++ vendor/modules.txt | 1 + 13 files changed, 51 insertions(+) create mode 100644 docs/source/markdown/options/env-merge.md (limited to 'docs') diff --git a/cmd/podman/common/create.go b/cmd/podman/common/create.go index 00873b95b..1e573cc2d 100644 --- a/cmd/podman/common/create.go +++ b/cmd/podman/common/create.go @@ -124,6 +124,14 @@ func DefineCreateFlags(cmd *cobra.Command, cf *entities.ContainerCreateOptions, "This is a Docker specific option and is a NOOP", ) + envMergeFlagName := "env-merge" + createFlags.StringArrayVar( + &cf.EnvMerge, + envMergeFlagName, []string{}, + "Preprocess environment variables from image before injecting them into the container", + ) + _ = cmd.RegisterFlagCompletionFunc(envMergeFlagName, completion.AutocompleteNone) + envFlagName := "env" createFlags.StringArrayP( envFlagName, "e", Env(), diff --git a/docs/source/markdown/options/env-merge.md b/docs/source/markdown/options/env-merge.md new file mode 100644 index 000000000..aa1aa003d --- /dev/null +++ b/docs/source/markdown/options/env-merge.md @@ -0,0 +1,5 @@ +#### **--env-merge**=*env* + +Preprocess default environment variables for the containers. For example +if image contains environment variable `hello=world` user can preprocess +it using `--env-merge hello=${hello}-some` so new value will be `hello=world-some`. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 9518568bb..0e65e7e3a 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -208,6 +208,8 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host +@@option env-merge + @@option expose #### **--gidmap**=*container_gid:host_gid:amount* diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 3e31ccc45..98d57a9c1 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -243,6 +243,8 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host +@@option env-merge + @@option expose #### **--gidmap**=*container_gid:host_gid:amount* diff --git a/go.mod b/go.mod index 635c0a17d..a694e6add 100644 --- a/go.mod +++ b/go.mod @@ -49,6 +49,7 @@ require ( github.com/opencontainers/runtime-spec v1.0.3-0.20211214071223-8958f93039ab github.com/opencontainers/runtime-tools v0.9.1-0.20220714195903-17b3287fafb7 github.com/opencontainers/selinux v1.10.1 + github.com/openshift/imagebuilder v1.2.4-0.20220711175835-4151e43600df github.com/rootless-containers/rootlesskit v1.0.1 github.com/sirupsen/logrus v1.9.0 github.com/spf13/cobra v1.5.0 diff --git a/pkg/api/handlers/compat/containers_create.go b/pkg/api/handlers/compat/containers_create.go index 9fff8b4c8..d4f5d5f36 100644 --- a/pkg/api/handlers/compat/containers_create.go +++ b/pkg/api/handlers/compat/containers_create.go @@ -408,6 +408,7 @@ func cliOpts(cc handlers.CreateContainerConfig, rtc *config.Config) (*entities.C Systemd: "true", // podman default TmpFS: parsedTmp, TTY: cc.Config.Tty, + EnvMerge: cc.EnvMerge, UnsetEnv: cc.UnsetEnv, UnsetEnvAll: cc.UnsetEnvAll, User: cc.Config.User, diff --git a/pkg/api/handlers/types.go b/pkg/api/handlers/types.go index b533e131c..ebbc5f63a 100644 --- a/pkg/api/handlers/types.go +++ b/pkg/api/handlers/types.go @@ -127,6 +127,7 @@ type CreateContainerConfig struct { dockerContainer.Config // desired container configuration HostConfig dockerContainer.HostConfig // host dependent configuration for container NetworkingConfig dockerNetwork.NetworkingConfig // network configuration for container + EnvMerge []string // preprocess env variables from image before injecting into containers UnsetEnv []string // unset specified default environment variables UnsetEnvAll bool // unset all default environment variables } diff --git a/pkg/domain/entities/pods.go b/pkg/domain/entities/pods.go index 14ce370c1..33ca2c807 100644 --- a/pkg/domain/entities/pods.go +++ b/pkg/domain/entities/pods.go @@ -263,6 +263,7 @@ type ContainerCreateOptions struct { TTY bool Timezone string Umask string + EnvMerge []string UnsetEnv []string UnsetEnvAll bool UIDMap []string diff --git a/pkg/specgen/generate/container.go b/pkg/specgen/generate/container.go index 85cd8f5ca..e293ce010 100644 --- a/pkg/specgen/generate/container.go +++ b/pkg/specgen/generate/container.go @@ -19,6 +19,7 @@ import ( "github.com/containers/podman/v4/pkg/signal" "github.com/containers/podman/v4/pkg/specgen" spec "github.com/opencontainers/runtime-spec/specs-go" + "github.com/openshift/imagebuilder" "github.com/sirupsen/logrus" "golang.org/x/sys/unix" ) @@ -131,6 +132,17 @@ func CompleteSpec(ctx context.Context, r *libpod.Runtime, s *specgen.SpecGenerat defaultEnvs = envLib.Join(envLib.DefaultEnvVariables(), envLib.Join(defaultEnvs, envs)) } + for _, e := range s.EnvMerge { + processedWord, err := imagebuilder.ProcessWord(e, envLib.Slice(defaultEnvs)) + if err != nil { + return nil, fmt.Errorf("unable to process variables for --env-merge %s: %w", e, err) + } + splitWord := strings.Split(processedWord, "=") + if _, ok := defaultEnvs[splitWord[0]]; ok { + defaultEnvs[splitWord[0]] = splitWord[1] + } + } + for _, e := range s.UnsetEnv { delete(defaultEnvs, e) } diff --git a/pkg/specgen/specgen.go b/pkg/specgen/specgen.go index b90f07ef8..51b6736a9 100644 --- a/pkg/specgen/specgen.go +++ b/pkg/specgen/specgen.go @@ -204,6 +204,9 @@ type ContainerBasicConfig struct { // The execution domain system allows Linux to provide limited support // for binaries compiled under other UNIX-like operating systems. Personality *spec.LinuxPersonality `json:"personality,omitempty"` + // EnvMerge takes the specified environment variables from image and preprocess them before injecting them into the + // container. + EnvMerge []string `json:"envmerge,omitempty"` // UnsetEnv unsets the specified default environment variables from the image or from buildin or containers.conf // Optional. UnsetEnv []string `json:"unsetenv,omitempty"` diff --git a/pkg/specgenutil/specgen.go b/pkg/specgenutil/specgen.go index 7392e7b44..aab2eebd5 100644 --- a/pkg/specgenutil/specgen.go +++ b/pkg/specgenutil/specgen.go @@ -839,6 +839,9 @@ func FillOutSpecGen(s *specgen.SpecGenerator, c *entities.ContainerCreateOptions if !s.Volatile { s.Volatile = c.Rm } + if len(s.EnvMerge) == 0 || len(c.EnvMerge) != 0 { + s.EnvMerge = c.EnvMerge + } if len(s.UnsetEnv) == 0 || len(c.UnsetEnv) != 0 { s.UnsetEnv = c.UnsetEnv } diff --git a/test/e2e/run_env_test.go b/test/e2e/run_env_test.go index bab52efc5..9e78e150a 100644 --- a/test/e2e/run_env_test.go +++ b/test/e2e/run_env_test.go @@ -82,6 +82,17 @@ var _ = Describe("Podman run", func() { Expect(session.OutputToString()).To(ContainSubstring("HOSTNAME")) }) + It("podman run with --env-merge", func() { + dockerfile := `FROM quay.io/libpod/alpine:latest +ENV hello=world +` + podmanTest.BuildImage(dockerfile, "test", "false") + session := podmanTest.Podman([]string{"run", "--rm", "--env-merge", "hello=${hello}-earth", "test", "env"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + Expect(session.OutputToString()).To(ContainSubstring("world-earth")) + }) + It("podman run --env-host environment test", func() { env := append(os.Environ(), "FOO=BAR") session := podmanTest.PodmanAsUser([]string{"run", "--rm", "--env-host", ALPINE, "/bin/printenv", "FOO"}, 0, 0, "", env) diff --git a/vendor/modules.txt b/vendor/modules.txt index eb9c7a34d..feb9f00d5 100644 --- a/vendor/modules.txt +++ b/vendor/modules.txt @@ -620,6 +620,7 @@ github.com/opencontainers/selinux/go-selinux/label github.com/opencontainers/selinux/pkg/pwalk github.com/opencontainers/selinux/pkg/pwalkdir # github.com/openshift/imagebuilder v1.2.4-0.20220711175835-4151e43600df +## explicit github.com/openshift/imagebuilder github.com/openshift/imagebuilder/dockerfile/command github.com/openshift/imagebuilder/dockerfile/parser -- cgit v1.2.3-54-g00ecf From c64a6ba07205c2f9fa2a874d9343babf68ee21d2 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 17:40:46 -0600 Subject: Man pages: Refactor common options: --workdir I chose the version from podman-run because it is the most up-to-date, and most correct wrt current syntax guidelines. Differences are in arg description, language, and asterisks. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 1 + docs/source/markdown/options/workdir.md | 7 ++ docs/source/markdown/podman-create.1.md.in | 8 +- docs/source/markdown/podman-exec.1.md | 121 ----------------------------- docs/source/markdown/podman-exec.1.md.in | 115 +++++++++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 8 +- 6 files changed, 125 insertions(+), 135 deletions(-) create mode 100644 docs/source/markdown/options/workdir.md delete mode 100644 docs/source/markdown/podman-exec.1.md create mode 100644 docs/source/markdown/podman-exec.1.md.in (limited to 'docs') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 2bdcce197..85aed3be0 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -3,6 +3,7 @@ podman-build.1.md podman-container-clone.1.md podman-container-runlabel.1.md podman-create.1.md +podman-exec.1.md podman-image-sign.1.md podman-kill.1.md podman-kube-play.1.md diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md new file mode 100644 index 000000000..12f3ddd44 --- /dev/null +++ b/docs/source/markdown/options/workdir.md @@ -0,0 +1,7 @@ +#### **--workdir**, **-w**=*dir* + +Working directory inside the container. + +The default working directory for running binaries within a container is the root directory (**/**). +The image developer can set a different default with the WORKDIR instruction. The operator +can override the working directory by using the **-w** option. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 9518568bb..8710af110 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -975,13 +975,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## EXAMPLES diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md deleted file mode 100644 index da61f3456..000000000 --- a/docs/source/markdown/podman-exec.1.md +++ /dev/null @@ -1,121 +0,0 @@ -% podman-exec(1) - -## NAME -podman\-exec - Execute a command in a running container - -## SYNOPSIS -**podman exec** [*options*] *container* [*command* [*arg* ...]] - -**podman container exec** [*options*] *container* [*command* [*arg* ...]] - -## DESCRIPTION -**podman exec** executes a command in a running container. - -## OPTIONS - -#### **--detach**, **-d** - -Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. - -#### **--detach-keys**=*sequence* - -Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-` characters where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. - -#### **--env**, **-e**=*env* - -Set environment variables. - -This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in __*__ is specified without a value, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. - -#### **--env-file**=*file* - -Read in a line delimited file of environment variables. - -#### **--interactive**, **-i** - -When set to true, keep stdin open even if not attached. The default is *false*. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--preserve-fds**=*N* - -Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. - -#### **--privileged** - -Give extended privileges to this container. The default is *false*. - -By default, Podman containers are -"unprivileged" and cannot, for example, modify parts of the operating system. -This is because by default a container is only allowed limited access to devices. -A "privileged" container is given the same access to devices as the user launching the container. - -A privileged container turns off the security features that isolate the -container from the host. Dropped Capabilities, limited devices, read/only mount -points, Apparmor/SELinux separation, and Seccomp filters are all disabled. - -Rootless containers cannot have more privileges than the account that launched them. - - -#### **--tty**, **-t** - -Allocate a pseudo-TTY. - -#### **--user**, **-u** - -Sets the username or UID used and optionally the groupname or GID for the specified command. -The following examples are all valid: ---user [user | user:group | uid | uid:gid | user:gid | uid:group ] - -#### **--workdir**, **-w**=*path* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction, which can be overridden -when creating the container. - -## Exit Status - -The exit code from `podman exec` gives information about why the command within the container failed to run or why it exited. When `podman exec` exits with a -non-zero code, the exit codes follow the `chroot` standard, see below: - - **125** The error is with Podman itself - - $ podman exec --foo ctrID /bin/sh; echo $? - Error: unknown flag: --foo - 125 - - **126** The _contained command_ cannot be invoked - - $ podman exec ctrID /etc; echo $? - Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error - 126 - - **127** The _contained command_ cannot be found - - $ podman exec ctrID foo; echo $? - Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error - 127 - - **Exit code** The _contained command_ exit code - - $ podman exec ctrID /bin/sh -c 'exit 3'; echo $? - 3 - -## EXAMPLES - -``` -$ podman exec -it ctrID ls -$ podman exec -it -w /tmp myCtr pwd -$ podman exec --user root ctrID ls -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)** - -## HISTORY -December 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in new file mode 100644 index 000000000..4f78f1c31 --- /dev/null +++ b/docs/source/markdown/podman-exec.1.md.in @@ -0,0 +1,115 @@ +% podman-exec(1) + +## NAME +podman\-exec - Execute a command in a running container + +## SYNOPSIS +**podman exec** [*options*] *container* [*command* [*arg* ...]] + +**podman container exec** [*options*] *container* [*command* [*arg* ...]] + +## DESCRIPTION +**podman exec** executes a command in a running container. + +## OPTIONS + +#### **--detach**, **-d** + +Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. + +#### **--detach-keys**=*sequence* + +Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-` characters where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. + +#### **--env**, **-e**=*env* + +Set environment variables. + +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in __*__ is specified without a value, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. + +#### **--env-file**=*file* + +Read in a line delimited file of environment variables. + +#### **--interactive**, **-i** + +When set to true, keep stdin open even if not attached. The default is *false*. + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--preserve-fds**=*N* + +Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. + +#### **--privileged** + +Give extended privileges to this container. The default is *false*. + +By default, Podman containers are +"unprivileged" and cannot, for example, modify parts of the operating system. +This is because by default a container is only allowed limited access to devices. +A "privileged" container is given the same access to devices as the user launching the container. + +A privileged container turns off the security features that isolate the +container from the host. Dropped Capabilities, limited devices, read/only mount +points, Apparmor/SELinux separation, and Seccomp filters are all disabled. + +Rootless containers cannot have more privileges than the account that launched them. + + +#### **--tty**, **-t** + +Allocate a pseudo-TTY. + +#### **--user**, **-u** + +Sets the username or UID used and optionally the groupname or GID for the specified command. +The following examples are all valid: +--user [user | user:group | uid | uid:gid | user:gid | uid:group ] + +@@option workdir + +## Exit Status + +The exit code from `podman exec` gives information about why the command within the container failed to run or why it exited. When `podman exec` exits with a +non-zero code, the exit codes follow the `chroot` standard, see below: + + **125** The error is with Podman itself + + $ podman exec --foo ctrID /bin/sh; echo $? + Error: unknown flag: --foo + 125 + + **126** The _contained command_ cannot be invoked + + $ podman exec ctrID /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + + **127** The _contained command_ cannot be found + + $ podman exec ctrID foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + + **Exit code** The _contained command_ exit code + + $ podman exec ctrID /bin/sh -c 'exit 3'; echo $? + 3 + +## EXAMPLES + +``` +$ podman exec -it ctrID ls +$ podman exec -it -w /tmp myCtr pwd +$ podman exec --user root ctrID ls +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)** + +## HISTORY +December 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 3e31ccc45..a0cd49d4e 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -1034,13 +1034,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container. - -The default working directory for running binaries within a container is the root directory (**/**). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## Exit Status -- cgit v1.2.3-54-g00ecf From ef6285a6f2a2040888772599b84dc5173f6257c7 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 18:47:31 -0600 Subject: Man pages: refactor common options: --gidmap Two versions: one for container-related commands, one for pods. The container one is easy: all versions matched, so I made no changes. The pod one is hard to review. I went with the pod-clone version because the pod-create one looks suspicious: it talks in terms of containers, not pods. It's possible that I've got it wrong, and that these two cannot be combined, so please review very carefully. I strongly recommend using hack/markdown-preprocess-review for this one. Signed-off-by: Ed Santiago --- docs/source/markdown/options/gidmap.container.md | 8 ++++++++ docs/source/markdown/options/gidmap.pod.md | 4 ++++ docs/source/markdown/podman-create.1.md.in | 9 +-------- docs/source/markdown/podman-pod-clone.1.md.in | 4 +--- docs/source/markdown/podman-pod-create.1.md.in | 4 +--- docs/source/markdown/podman-run.1.md.in | 9 +-------- 6 files changed, 16 insertions(+), 22 deletions(-) create mode 100644 docs/source/markdown/options/gidmap.container.md create mode 100644 docs/source/markdown/options/gidmap.pod.md (limited to 'docs') diff --git a/docs/source/markdown/options/gidmap.container.md b/docs/source/markdown/options/gidmap.container.md new file mode 100644 index 000000000..a3c9df33d --- /dev/null +++ b/docs/source/markdown/options/gidmap.container.md @@ -0,0 +1,8 @@ +#### **--gidmap**=*container_gid:host_gid:amount* + +Run the container in a new user namespace using the supplied GID mapping. This +option conflicts with the **--userns** and **--subgidname** options. This +option provides a way to map host GIDs to container GIDs in the same way as +__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. + +Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/gidmap.pod.md b/docs/source/markdown/options/gidmap.pod.md new file mode 100644 index 000000000..0d58cc527 --- /dev/null +++ b/docs/source/markdown/options/gidmap.pod.md @@ -0,0 +1,4 @@ +#### **--gidmap**=*pod_gid:host_gid:amount* + +GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. +It conflicts with the **--userns** and **--subgidname** flags. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 8710af110..7b02430e0 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -210,14 +210,7 @@ Read in a line delimited file of environment variables. See **Environment** note @@option expose -#### **--gidmap**=*container_gid:host_gid:amount* - -Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This -option provides a way to map host GIDs to container GIDs in the same way as -__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. - -Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. +@@option gidmap.container @@option group-add diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index a5746fd84..c040f1c27 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -56,9 +56,7 @@ Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sd Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) -#### **--gidmap**=*pod_gid:host_gid:amount* - -GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. +@@option gidmap.pod #### **--help**, **-h** diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index c12f296b4..702780c65 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -94,9 +94,7 @@ Set the exit policy of the pod when the last container exits. Supported policie | *continue* | The pod continues running, by keeping its infra container alive, when the last container exits. Used by default. | | *stop* | The pod (including its infra container) is stopped when the last container exits. Used in `kube play`. | -#### **--gidmap**=*container_gid:host_gid:amount* - -GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. +@@option gidmap.pod #### **--help**, **-h** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index a0cd49d4e..8457a7fa6 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -245,14 +245,7 @@ Read in a line delimited file of environment variables. See **Environment** note @@option expose -#### **--gidmap**=*container_gid:host_gid:amount* - -Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This -option provides a way to map host GIDs to container GIDs in the same way as -__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. - -Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. +@@option gidmap.container @@option group-add -- cgit v1.2.3-54-g00ecf From 33ab7e846acb025dcc905634c6942d1dd6d0a4e2 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 15:28:48 -0600 Subject: Man pages: refactor common options: --ipc This is not an easy one to review, sorry. I went with the version from podman-create. The differences against podman-run are subtle: apostrophes, whitespace, and the arg description in the '####' line. Suggestion for review: run hack/markdown-preprocess-review, then after you finish with that, cd /tmp/markdown/ipc and use your favorite two-file diff tool to compare podman-run* against zzz*. I did not even try to combine the podman-build one; that one is too different. Signed-off-by: Ed Santiago --- docs/source/markdown/options/ipc.md | 12 ++++++++++++ docs/source/markdown/podman-create.1.md.in | 13 +------------ docs/source/markdown/podman-run.1.md.in | 13 +------------ 3 files changed, 14 insertions(+), 24 deletions(-) create mode 100644 docs/source/markdown/options/ipc.md (limited to 'docs') diff --git a/docs/source/markdown/options/ipc.md b/docs/source/markdown/options/ipc.md new file mode 100644 index 000000000..699b64eec --- /dev/null +++ b/docs/source/markdown/options/ipc.md @@ -0,0 +1,12 @@ +#### **--ipc**=*ipc* + +Set the IPC namespace mode for a container. The default is to create +a private IPC namespace. + +- "": Use Podman's default, defined in containers.conf. +- **container:**_id_: reuses another container's shared memory, semaphores, and message queues +- **host**: use the host's shared memory, semaphores, and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. +- **none**: private IPC namespace, with /dev/shm not mounted. +- **ns:**_path_: path to an IPC namespace to join. +- **private**: private IPC namespace. += **shareable**: private IPC namespace with a possibility to share it with other containers. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 7b02430e0..dec560080 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -296,18 +296,7 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--ipc**=*ipc* - -Set the IPC namespace mode for a container. The default is to create -a private IPC namespace. - -- "": Use Podman's default, defined in containers.conf. -- **container:**_id_: reuses another container's shared memory, semaphores, and message queues -- **host**: use the host's shared memory, semaphores, and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. -- **none**: private IPC namespace, with /dev/shm not mounted. -- **ns:**_path_: path to an IPC namespace to join. -- **private**: private IPC namespace. -= **shareable**: private IPC namespace with a possibility to share it with other containers. +@@option ipc #### **--label**, **-l**=*label* diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 8457a7fa6..b77ccf945 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -310,18 +310,7 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--ipc**=*mode* - -Set the IPC namespace mode for a container. The default is to create -a private IPC namespace. - -- "": Use Podman's default, defined in containers.conf. -- **container:**_id_: reuses another container shared memory, semaphores and message queues -- **host**: use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. -- **none**: private IPC namespace, with /dev/shm not mounted. -- **ns:**_path_: path to an IPC namespace to join. -- **private**: private IPC namespace. -= **shareable**: private IPC namespace with a possibility to share it with other containers. +@@option ipc #### **--label**, **-l**=*key=value* -- cgit v1.2.3-54-g00ecf From 2fed2a2829a796307a58ead516ed8dea97a4a4d1 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 24 Aug 2022 09:16:37 -0600 Subject: Man pages: refactor common options: --pid I chose the one from podman-run, but reordered ns/private to put them in alphabetical order. Signed-off-by: Ed Santiago --- docs/source/markdown/options/pid.md | 9 +++++++++ docs/source/markdown/podman-create.1.md.in | 9 +-------- docs/source/markdown/podman-run.1.md.in | 10 +--------- 3 files changed, 11 insertions(+), 17 deletions(-) create mode 100644 docs/source/markdown/options/pid.md (limited to 'docs') diff --git a/docs/source/markdown/options/pid.md b/docs/source/markdown/options/pid.md new file mode 100644 index 000000000..d0cbef1d5 --- /dev/null +++ b/docs/source/markdown/options/pid.md @@ -0,0 +1,9 @@ +#### **--pid**=*mode* + +Set the PID namespace mode for the container. +The default is to create a private PID namespace for the container. + +- **container:**_id_: join another container's PID namespace; +- **host**: use the host's PID namespace for the container. Note the host mode gives the container full access to local PID and is therefore considered insecure; +- **ns:**_path_: join the specified PID namespace; +- **private**: create a new namespace for the container (default). diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index f002418c5..4dbc75551 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -437,14 +437,7 @@ Unless overridden, subsequent lookups of the same image in the local storage wil @@option personality -#### **--pid**=*pid* - -Set the PID mode for the container -Default is to create a private PID namespace for the container -- `container:`: join another container's PID namespace -- `host`: use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure. -- `ns`: join the specified PID namespace -- `private`: create a new namespace for the container (default) +@@option pid @@option pidfile diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index a5a8ac6c5..c7985d7e1 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -458,15 +458,7 @@ This is used to override the Podman provided user setup in favor of entrypoint c @@option personality -#### **--pid**=*mode* - -Set the PID namespace mode for the container. -The default is to create a private PID namespace for the container. - -- **container:**_id_: join another container's PID namespace; -- **host**: use the host's PID namespace for the container. Note the host mode gives the container full access to local PID and is therefore considered insecure; -- **private**: create a new namespace for the container (default) -- **ns:**_path_: join the specified PID namespace. +@@option pid @@option pidfile -- cgit v1.2.3-54-g00ecf From 0ff0fde49e8d31b4fb9882dc12e1c17e6a641512 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 24 Aug 2022 17:38:05 -0600 Subject: Man pages: refactor common options: log-related options podman-logs and podman-pod-logs. Most of these were already identical, needing no review. Exceptions: --follow : needed some container/pod tweaking. This is the only one that really needs careful review. --names : I went with the longer version Note that podman-events has --since and --until options too, but those are too different to be combined here. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 2 + docs/source/markdown/options/color.md | 3 + docs/source/markdown/options/follow.md | 7 ++ docs/source/markdown/options/names.md | 3 + docs/source/markdown/options/since.md | 6 ++ docs/source/markdown/options/tail.md | 4 + docs/source/markdown/options/timestamps.md | 3 + docs/source/markdown/options/until.md | 6 ++ docs/source/markdown/podman-logs.1.md | 134 --------------------------- docs/source/markdown/podman-logs.1.md.in | 109 ++++++++++++++++++++++ docs/source/markdown/podman-pod-logs.1.md | 95 ------------------- docs/source/markdown/podman-pod-logs.1.md.in | 71 ++++++++++++++ 12 files changed, 214 insertions(+), 229 deletions(-) create mode 100644 docs/source/markdown/options/color.md create mode 100644 docs/source/markdown/options/follow.md create mode 100644 docs/source/markdown/options/names.md create mode 100644 docs/source/markdown/options/since.md create mode 100644 docs/source/markdown/options/tail.md create mode 100644 docs/source/markdown/options/timestamps.md create mode 100644 docs/source/markdown/options/until.md delete mode 100644 docs/source/markdown/podman-logs.1.md create mode 100644 docs/source/markdown/podman-logs.1.md.in delete mode 100644 docs/source/markdown/podman-pod-logs.1.md create mode 100644 docs/source/markdown/podman-pod-logs.1.md.in (limited to 'docs') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 85aed3be0..8a0d553ba 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -9,11 +9,13 @@ podman-kill.1.md podman-kube-play.1.md podman-login.1.md podman-logout.1.md +podman-logs.1.md podman-manifest-add.1.md podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-logs.1.md podman-pod-rm.1.md podman-pod-start.1.md podman-pod-stop.1.md diff --git a/docs/source/markdown/options/color.md b/docs/source/markdown/options/color.md new file mode 100644 index 000000000..343c79c88 --- /dev/null +++ b/docs/source/markdown/options/color.md @@ -0,0 +1,3 @@ +#### **--color** + +Output the containers with different colors in the log. diff --git a/docs/source/markdown/options/follow.md b/docs/source/markdown/options/follow.md new file mode 100644 index 000000000..75b65cf49 --- /dev/null +++ b/docs/source/markdown/options/follow.md @@ -0,0 +1,7 @@ +#### **--follow**, **-f** + +Follow log output. Default is false. + +Note: If you are following a <> which is removed by `podman <> rm` +or removed on exit (`podman run --rm ...`), then there is a chance that the log +file will be removed before `podman<< pod|>> logs` reads the final content. diff --git a/docs/source/markdown/options/names.md b/docs/source/markdown/options/names.md new file mode 100644 index 000000000..54fda40ee --- /dev/null +++ b/docs/source/markdown/options/names.md @@ -0,0 +1,3 @@ +#### **--names**, **-n** + +Output the container names instead of the container IDs in the log. diff --git a/docs/source/markdown/options/since.md b/docs/source/markdown/options/since.md new file mode 100644 index 000000000..9f20722df --- /dev/null +++ b/docs/source/markdown/options/since.md @@ -0,0 +1,6 @@ +#### **--since**=*TIMESTAMP* + +Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. diff --git a/docs/source/markdown/options/tail.md b/docs/source/markdown/options/tail.md new file mode 100644 index 000000000..463b6fc3f --- /dev/null +++ b/docs/source/markdown/options/tail.md @@ -0,0 +1,4 @@ +#### **--tail**=*LINES* + +Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, +which prints all lines diff --git a/docs/source/markdown/options/timestamps.md b/docs/source/markdown/options/timestamps.md new file mode 100644 index 000000000..a449216aa --- /dev/null +++ b/docs/source/markdown/options/timestamps.md @@ -0,0 +1,3 @@ +#### **--timestamps**, **-t** + +Show timestamps in the log outputs. The default is false diff --git a/docs/source/markdown/options/until.md b/docs/source/markdown/options/until.md new file mode 100644 index 000000000..d656d976b --- /dev/null +++ b/docs/source/markdown/options/until.md @@ -0,0 +1,6 @@ +#### **--until**=*TIMESTAMP* + +Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md deleted file mode 100644 index 6ce6c3812..000000000 --- a/docs/source/markdown/podman-logs.1.md +++ /dev/null @@ -1,134 +0,0 @@ -% podman-logs(1) - -## NAME -podman\-logs - Display the logs of one or more containers - -## SYNOPSIS -**podman logs** [*options*] *container* [*container...*] - -**podman container logs** [*options*] *container* [*container...*] - -## DESCRIPTION -The podman logs command batch-retrieves whatever logs are present for one or more containers at the time of execution. -This does not guarantee execution order when combined with podman run (i.e. your run may not have generated -any logs at the time you execute podman logs). - -## OPTIONS - -#### **--color** - -Output the containers with different colors in the log. - -#### **--follow**, **-f** - -Follow log output. Default is false. - -Note: If you are following a container which is removed `podman container rm` -or removed on exit `podman run --rm ...`, then there is a chance that the log -file will be removed before `podman logs` reads the final content. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--names**, **-n** - -Output the container name in the log - -#### **--since**=*TIMESTAMP* - -Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -#### **--tail**=*LINES* - -Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, -which prints all lines - -#### **--timestamps**, **-t** - -Show timestamps in the log outputs. The default is false - -#### **--until**=*TIMESTAMP* - -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -## EXAMPLE - -To view a container's logs: -``` -podman logs -t b3f2436bdb978c1d33b1387afb5d7ba7e3243ed2ce908db431ac0069da86cb45 - -2017/08/07 10:16:21 Seeked /var/log/crio/pods/eb296bd56fab164d4d3cc46e5776b54414af3bf543d138746b25832c816b933b/c49f49788da14f776b7aa93fb97a2a71f9912f4e5a3e30397fca7dfe0ee0367b.log - &{Offset:0 Whence:0} -1:C 07 Aug 14:10:09.055 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo -1:C 07 Aug 14:10:09.055 # Redis version=4.0.1, bits=64, commit=00000000, modified=0, pid=1, just started -1:C 07 Aug 14:10:09.055 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf -1:M 07 Aug 14:10:09.055 # You requested maxclients of 10000 requiring at least 10032 max file descriptors. -1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. -1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. -1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. -1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. -1:M 07 Aug 14:10:09.056 # Server initialized -``` - -To view only the last two lines in container's log: -``` -podman logs --tail 2 b3f2436bdb97 - -# WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. -# Server initialized -``` - -To view all containers logs: -``` -podman logs -t --since 0 myserver - -1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. -1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. -1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. -1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. -1:M 07 Aug 14:10:09.056 # Server initialized -``` - -To view a containers logs since a certain time: -``` -podman logs -t --since 2017-08-07T10:10:09.055837383-04:00 myserver - -1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. -1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. -1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. -1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. -1:M 07 Aug 14:10:09.056 # Server initialized -``` - -To view a container's logs generated in the last 10 minutes: -``` -podman logs --since 10m myserver - -# Server can't set maximum open files to 10032 because of OS error: Operation not permitted. -# Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. -``` - -To view a container's logs until 30 minutes ago: -``` -podman logs --until 30m myserver - -AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 10.0.2.100. Set the 'ServerName' directive globally to suppress this message -AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 10.0.2.100. Set the 'ServerName' directive globally to suppress this message -[Tue Jul 20 13:18:14.223727 2021] [mpm_event:notice] [pid 1:tid 140021067187328] AH00489: Apache/2.4.48 (Unix) configured -- resuming normal operations -[Tue Jul 20 13:18:14.223819 2021] [core:notice] [pid 1:tid 140021067187328] AH00094: Command line: 'httpd -D FOREGROUND' -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-container-rm(1)](podman-container-rm.1.md)** - -## HISTORY -February 2018, Updated by Brent Baude - -August 2017, Originally compiled by Ryan Cole diff --git a/docs/source/markdown/podman-logs.1.md.in b/docs/source/markdown/podman-logs.1.md.in new file mode 100644 index 000000000..7b0c45cf0 --- /dev/null +++ b/docs/source/markdown/podman-logs.1.md.in @@ -0,0 +1,109 @@ +% podman-logs(1) + +## NAME +podman\-logs - Display the logs of one or more containers + +## SYNOPSIS +**podman logs** [*options*] *container* [*container...*] + +**podman container logs** [*options*] *container* [*container...*] + +## DESCRIPTION +The podman logs command batch-retrieves whatever logs are present for one or more containers at the time of execution. +This does not guarantee execution order when combined with podman run (i.e. your run may not have generated +any logs at the time you execute podman logs). + +## OPTIONS + +@@option color + +@@option follow + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option names + +@@option since + +@@option tail + +@@option timestamps + +@@option until + +## EXAMPLE + +To view a container's logs: +``` +podman logs -t b3f2436bdb978c1d33b1387afb5d7ba7e3243ed2ce908db431ac0069da86cb45 + +2017/08/07 10:16:21 Seeked /var/log/crio/pods/eb296bd56fab164d4d3cc46e5776b54414af3bf543d138746b25832c816b933b/c49f49788da14f776b7aa93fb97a2a71f9912f4e5a3e30397fca7dfe0ee0367b.log - &{Offset:0 Whence:0} +1:C 07 Aug 14:10:09.055 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo +1:C 07 Aug 14:10:09.055 # Redis version=4.0.1, bits=64, commit=00000000, modified=0, pid=1, just started +1:C 07 Aug 14:10:09.055 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf +1:M 07 Aug 14:10:09.055 # You requested maxclients of 10000 requiring at least 10032 max file descriptors. +1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. +1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 07 Aug 14:10:09.056 # Server initialized +``` + +To view only the last two lines in container's log: +``` +podman logs --tail 2 b3f2436bdb97 + +# WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +# Server initialized +``` + +To view all containers logs: +``` +podman logs -t --since 0 myserver + +1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. +1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 07 Aug 14:10:09.056 # Server initialized +``` + +To view a containers logs since a certain time: +``` +podman logs -t --since 2017-08-07T10:10:09.055837383-04:00 myserver + +1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. +1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 07 Aug 14:10:09.056 # Server initialized +``` + +To view a container's logs generated in the last 10 minutes: +``` +podman logs --since 10m myserver + +# Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +# Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +``` + +To view a container's logs until 30 minutes ago: +``` +podman logs --until 30m myserver + +AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 10.0.2.100. Set the 'ServerName' directive globally to suppress this message +AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 10.0.2.100. Set the 'ServerName' directive globally to suppress this message +[Tue Jul 20 13:18:14.223727 2021] [mpm_event:notice] [pid 1:tid 140021067187328] AH00489: Apache/2.4.48 (Unix) configured -- resuming normal operations +[Tue Jul 20 13:18:14.223819 2021] [core:notice] [pid 1:tid 140021067187328] AH00094: Command line: 'httpd -D FOREGROUND' +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-container-rm(1)](podman-container-rm.1.md)** + +## HISTORY +February 2018, Updated by Brent Baude + +August 2017, Originally compiled by Ryan Cole diff --git a/docs/source/markdown/podman-pod-logs.1.md b/docs/source/markdown/podman-pod-logs.1.md deleted file mode 100644 index 7fc1d4b90..000000000 --- a/docs/source/markdown/podman-pod-logs.1.md +++ /dev/null @@ -1,95 +0,0 @@ -% podman-pod-logs(1) - -## NAME -podman\-pod\-logs - Displays logs for pod with one or more containers - -## SYNOPSIS -**podman pod logs** [*options*] *pod* - -## DESCRIPTION -The podman pod logs command batch-retrieves whatever logs are present with all the containers of a pod. Pod logs can be filtered by container name or id using flag **-c** or **--container** if needed. - -Note: Long running command of `podman pod log` with a `-f` or `--follow` needs to be reinvoked if new container is added to the pod dynamically otherwise logs of newly added containers would not be visible in log stream. - -## OPTIONS - -#### **--color** - -Output the containers with different colors in the log. - -#### **--container**, **-c** - -By default `podman pod logs` retrieves logs for all the containers available within the pod differentiate by field `container`. However there are use-cases where user would want to limit the log stream only to a particular container of a pod for such cases `-c` can be used like `podman pod logs -c ctrNameorID podname`. - -#### **--follow**, **-f** - -Follow log output. Default is false. - -Note: If you are following a pod which is removed `podman pod rm`, then there is a -chance that the log file will be removed before `podman pod logs` reads the final content. - -#### **--latest**, **-l** - -Instead of providing the pod name or id, get logs of the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--names**, **-n** - -Output the container names instead of the container IDs in the log. - -#### **--since**=*TIMESTAMP* - -Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -#### **--tail**=*LINES* - -Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, -which prints all lines - -#### **--timestamps**, **-t** - -Show timestamps in the log outputs. The default is false - -#### **--until**=*TIMESTAMP* - -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -## EXAMPLE - -To view a pod's logs: -``` -podman pod logs -t podIdorName -``` - -To view logs of a specific container on the pod -``` -podman pod logs -c ctrIdOrName podIdOrName -``` - -To view all pod logs: -``` -podman pod logs -t --since 0 myserver-pod-1 -``` - -To view a pod's logs since a certain time: -``` -podman pod logs -t --since 2017-08-07T10:10:09.055837383-04:00 myserver-pod-1 -``` - -To view a pod's logs generated in the last 10 minutes: -``` -podman pod logs --since 10m myserver-pod-1 -``` - -To view a pod's logs until 30 minutes ago: -``` -podman pod logs --until 30m myserver-pod-1 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-rm(1)](podman-pod-rm.1.md)**, **[podman-logs(1)](podman-logs.1.md)** diff --git a/docs/source/markdown/podman-pod-logs.1.md.in b/docs/source/markdown/podman-pod-logs.1.md.in new file mode 100644 index 000000000..391f620f8 --- /dev/null +++ b/docs/source/markdown/podman-pod-logs.1.md.in @@ -0,0 +1,71 @@ +% podman-pod-logs(1) + +## NAME +podman\-pod\-logs - Displays logs for pod with one or more containers + +## SYNOPSIS +**podman pod logs** [*options*] *pod* + +## DESCRIPTION +The podman pod logs command batch-retrieves whatever logs are present with all the containers of a pod. Pod logs can be filtered by container name or id using flag **-c** or **--container** if needed. + +Note: Long running command of `podman pod log` with a `-f` or `--follow` needs to be reinvoked if new container is added to the pod dynamically otherwise logs of newly added containers would not be visible in log stream. + +## OPTIONS + +@@option color + +#### **--container**, **-c** + +By default `podman pod logs` retrieves logs for all the containers available within the pod differentiate by field `container`. However there are use-cases where user would want to limit the log stream only to a particular container of a pod for such cases `-c` can be used like `podman pod logs -c ctrNameorID podname`. + +@@option follow + +#### **--latest**, **-l** + +Instead of providing the pod name or id, get logs of the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option names + +@@option since + +@@option tail + +@@option timestamps + +@@option until + +## EXAMPLE + +To view a pod's logs: +``` +podman pod logs -t podIdorName +``` + +To view logs of a specific container on the pod +``` +podman pod logs -c ctrIdOrName podIdOrName +``` + +To view all pod logs: +``` +podman pod logs -t --since 0 myserver-pod-1 +``` + +To view a pod's logs since a certain time: +``` +podman pod logs -t --since 2017-08-07T10:10:09.055837383-04:00 myserver-pod-1 +``` + +To view a pod's logs generated in the last 10 minutes: +``` +podman pod logs --since 10m myserver-pod-1 +``` + +To view a pod's logs until 30 minutes ago: +``` +podman pod logs --until 30m myserver-pod-1 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-rm(1)](podman-pod-rm.1.md)**, **[podman-logs(1)](podman-logs.1.md)** -- cgit v1.2.3-54-g00ecf From ff3f574fc0db5e442adfac54b86af7c462595ffc Mon Sep 17 00:00:00 2001 From: Miloslav Trmač Date: Wed, 24 Aug 2022 19:48:26 +0200 Subject: Add support for sigstoreSigned in (podman image trust set) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit NOTE: This does not edit the use-sigstore-attachments value in registries.d, similarly to how (podman image trust set) didn't set the lookaside paths for simple signing. Signed-off-by: Miloslav Trmač --- cmd/podman/images/trust_set.go | 4 ++-- docs/source/markdown/podman-image-trust.1.md | 9 ++++++--- pkg/trust/policy.go | 8 ++++++++ pkg/trust/policy_test.go | 22 ++++++++++++++++++++++ 4 files changed, 38 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/cmd/podman/images/trust_set.go b/cmd/podman/images/trust_set.go index 832e9f724..e7339f0b1 100644 --- a/cmd/podman/images/trust_set.go +++ b/cmd/podman/images/trust_set.go @@ -53,7 +53,7 @@ File(s) must exist before using this command`) } func setTrust(cmd *cobra.Command, args []string) error { - validTrustTypes := []string{"accept", "insecureAcceptAnything", "reject", "signedBy"} + validTrustTypes := []string{"accept", "insecureAcceptAnything", "reject", "signedBy", "sigstoreSigned"} valid, err := isValidImageURI(args[0]) if err != nil || !valid { @@ -61,7 +61,7 @@ func setTrust(cmd *cobra.Command, args []string) error { } if !util.StringInSlice(setOptions.Type, validTrustTypes) { - return fmt.Errorf("invalid choice: %s (choose from 'accept', 'reject', 'signedBy')", setOptions.Type) + return fmt.Errorf("invalid choice: %s (choose from 'accept', 'reject', 'signedBy', 'sigstoreSigned')", setOptions.Type) } return registry.ImageEngine().SetTrust(registry.Context(), args, setOptions) } diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 4e80bdcf5..2a7da82cc 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -32,7 +32,8 @@ Trust **type** provides a way to: Allowlist ("accept") or Denylist ("reject") registries or -Require signature (“signedBy”). +Require a simple signing signature (“signedBy”), +Require a sigstore signature ("sigstoreSigned"). Trust may be updated using the command **podman image trust set** for an existing trust scope. @@ -45,12 +46,14 @@ Trust may be updated using the command **podman image trust set** for an existin #### **--pubkeysfile**, **-f**=*KEY1* A path to an exported public key on the local system. Key paths will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to - require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. + require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** and **sigstoreSigned** types. #### **--type**, **-t**=*value* The trust type for this policy entry. Accepted values: - **signedBy** (default): Require signatures with corresponding list of + **signedBy** (default): Require simple signing signatures with corresponding list of + public keys + **sigstoreSigned**: Require sigstore signatures with corresponding list of public keys **accept**: do not require any signatures for this registry scope diff --git a/pkg/trust/policy.go b/pkg/trust/policy.go index 77e02a05c..3a31b9338 100644 --- a/pkg/trust/policy.go +++ b/pkg/trust/policy.go @@ -161,6 +161,14 @@ func AddPolicyEntries(policyPath string, input AddPolicyEntriesInput) error { newReposContent = append(newReposContent, RepoContent{Type: trustType, KeyType: "GPGKeys", KeyPath: filepath}) } + case "sigstoreSigned": + if len(pubkeysfile) == 0 { + return errors.New("at least one public key must be defined for type 'sigstoreSigned'") + } + for _, filepath := range pubkeysfile { + newReposContent = append(newReposContent, RepoContent{Type: trustType, KeyPath: filepath}) + } + default: return fmt.Errorf("unknown trust type %q", input.Type) } diff --git a/pkg/trust/policy_test.go b/pkg/trust/policy_test.go index c4781335f..c2c2d93be 100644 --- a/pkg/trust/policy_test.go +++ b/pkg/trust/policy_test.go @@ -47,6 +47,11 @@ func TestAddPolicyEntries(t *testing.T) { Type: "signedBy", PubKeyFiles: []string{}, // A key is missing }, + { + Scope: "default", + Type: "sigstoreSigned", + PubKeyFiles: []string{}, // A key is missing + }, { Scope: "default", Type: "this-is-unknown", @@ -73,6 +78,12 @@ func TestAddPolicyEntries(t *testing.T) { PubKeyFiles: []string{"/1.pub", "/2.pub"}, }) assert.NoError(t, err) + err = AddPolicyEntries(policyPath, AddPolicyEntriesInput{ + Scope: "quay.io/sigstore-signed", + Type: "sigstoreSigned", + PubKeyFiles: []string{"/1.pub", "/2.pub"}, + }) + assert.NoError(t, err) // Test that the outcome is consumable, and compare it with the expected values. parsedPolicy, err := signature.NewPolicyFromFile(policyPath) @@ -90,6 +101,10 @@ func TestAddPolicyEntries(t *testing.T) { xNewPRSignedByKeyPath(t, "/1.pub", signature.NewPRMMatchRepoDigestOrExact()), xNewPRSignedByKeyPath(t, "/2.pub", signature.NewPRMMatchRepoDigestOrExact()), }, + "quay.io/sigstore-signed": { + xNewPRSigstoreSignedKeyPath(t, "/1.pub", signature.NewPRMMatchRepoDigestOrExact()), + xNewPRSigstoreSignedKeyPath(t, "/2.pub", signature.NewPRMMatchRepoDigestOrExact()), + }, }, }, }, parsedPolicy) @@ -101,3 +116,10 @@ func xNewPRSignedByKeyPath(t *testing.T, keyPath string, signedIdentity signatur require.NoError(t, err) return pr } + +// xNewPRSigstoreSignedKeyPath is a wrapper for NewPRSigstoreSignedKeyPath which must not fail. +func xNewPRSigstoreSignedKeyPath(t *testing.T, keyPath string, signedIdentity signature.PolicyReferenceMatch) signature.PolicyRequirement { + pr, err := signature.NewPRSigstoreSignedKeyPath(keyPath, signedIdentity) + require.NoError(t, err) + return pr +} -- cgit v1.2.3-54-g00ecf From 42fdc72aa8b56bd4ff04ba497c46a5f2978d9f2a Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 24 Aug 2022 18:00:11 -0600 Subject: Man pages: refactor common options: --systemd I went with the podman-run version, which better conforms to style conventions. Signed-off-by: Ed Santiago --- docs/source/markdown/options/systemd.md | 29 +++++++++++++++++++++++++++++ docs/source/markdown/podman-create.1.md.in | 29 +---------------------------- docs/source/markdown/podman-run.1.md.in | 30 +----------------------------- 3 files changed, 31 insertions(+), 57 deletions(-) create mode 100644 docs/source/markdown/options/systemd.md (limited to 'docs') diff --git a/docs/source/markdown/options/systemd.md b/docs/source/markdown/options/systemd.md new file mode 100644 index 000000000..a341edbc2 --- /dev/null +++ b/docs/source/markdown/options/systemd.md @@ -0,0 +1,29 @@ +#### **--systemd**=*true* | *false* | *always* + +Run container in systemd mode. The default is **true**. + +The value *always* enforces the systemd mode is enforced without +looking at the executable name. Otherwise, if set to true and the +command you are running inside the container is **systemd**, **/usr/sbin/init**, +**/sbin/init** or **/usr/local/sbin/init**. + +Running the container in systemd mode causes the following changes: + +* Podman mounts tmpfs file systems on the following directories + * _/run_ + * _/run/lock_ + * _/tmp_ + * _/sys/fs/cgroup/systemd_ + * _/var/lib/journal_ +* Podman sets the default stop signal to **SIGRTMIN+3**. +* Podman sets **container_uuid** environment variable in the container to the +first 32 characters of the container id. + +This allows systemd to run in a confined container without any modifications. + +Note that on **SELinux** systems, systemd attempts to write to the cgroup +file system. Containers writing to the cgroup file system are denied by default. +The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system. +``` +setsebool -P container_manage_cgroup true +``` diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 4dbc75551..1ff7429c7 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -632,34 +632,7 @@ Network Namespace - current sysctls allowed: Note: if you use the --network=host option these sysctls will not be allowed. -#### **--systemd**=*true* | *false* | *always* - -Run container in systemd mode. The default is *true*. - -The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to true and the -command you are running inside the container is **systemd**, **/usr/sbin/init**, -**/sbin/init** or **/usr/local/sbin/init**. - -Running the container in systemd mode causes the following changes: - -* Podman mounts tmpfs file systems on the following directories - * _/run_ - * _/run/lock_ - * _/tmp_ - * _/sys/fs/cgroup/systemd_ - * _/var/lib/journal_ -* Podman sets the default stop signal to **SIGRTMIN+3**. -* Podman sets **container_uuid** environment variable in the container to the -first 32 characters of the container id. - -This allows systemd to run in a confined container without any modifications. - -Note: On `SELinux` systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. -The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system. - -`setsebool -P container_manage_cgroup true` +@@option systemd @@option timeout diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index c7985d7e1..f172ffc9e 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -682,35 +682,7 @@ For the network namespace, the following sysctls are allowed: Note: if you use the **--network=host** option, these sysctls will not be allowed. -#### **--systemd**=*true* | *false* | *always* - -Run container in systemd mode. The default is **true**. - -The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to true and the -command you are running inside the container is **systemd**, **/usr/sbin/init**, -**/sbin/init** or **/usr/local/sbin/init**. - -Running the container in systemd mode causes the following changes: - -* Podman mounts tmpfs file systems on the following directories - * _/run_ - * _/run/lock_ - * _/tmp_ - * _/sys/fs/cgroup/systemd_ - * _/var/lib/journal_ -* Podman sets the default stop signal to **SIGRTMIN+3**. -* Podman sets **container_uuid** environment variable in the container to the -first 32 characters of the container id. - -This allows systemd to run in a confined container without any modifications. - -Note that on **SELinux** systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. -The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system. -``` -setsebool -P container_manage_cgroup true -``` +@@option systemd @@option timeout -- cgit v1.2.3-54-g00ecf From 61d842a183b1ce623c70a571d095846c7b03ab11 Mon Sep 17 00:00:00 2001 From: Stefano Figura Date: Fri, 26 Aug 2022 15:34:05 +0200 Subject: Fix template name inconsistency Signed-off-by: Stefano Figura --- docs/source/markdown/podman-generate-systemd.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index fc2ce171e..88dff2a45 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -26,7 +26,7 @@ therefore the overridden default value._ A Kubernetes YAML can be executed in systemd via the `podman-kube@.service` systemd template. The template's argument is the path to the YAML file. Given a `workload.yaml` file in the home directory, it can be executed as follows: ``` -$ escaped=$(systemd-escape ~/sysadmin.yaml) +$ escaped=$(systemd-escape ~/workload.yaml) $ systemctl --user start podman-kube@$escaped.service $ systemctl --user is-active podman-kube@$escaped.service active -- cgit v1.2.3-54-g00ecf From 11de12097fa21f696ca70218b15a0552663e7e22 Mon Sep 17 00:00:00 2001 From: patrycja-guzik Date: Sat, 27 Aug 2022 00:01:22 +0200 Subject: Fix example sections to follow the same format Signed-off-by: patrycja-guzik --- docs/source/markdown/podman-pod-restart.1.md | 11 ++++++++++- docs/source/markdown/podman-pod-stop.1.md.in | 8 ++++---- docs/source/markdown/podman-rename.1.md | 6 +++--- docs/source/markdown/podman-rm.1.md.in | 14 +++++++------- 4 files changed, 24 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/source/markdown/podman-pod-restart.1.md b/docs/source/markdown/podman-pod-restart.1.md index 677eca3a3..51f13dbf8 100644 --- a/docs/source/markdown/podman-pod-restart.1.md +++ b/docs/source/markdown/podman-pod-restart.1.md @@ -24,17 +24,27 @@ Instead of providing the pod name or ID, restart the last created pod. (This opt ## EXAMPLE +Restart pod with a given name ``` podman pod restart mywebserverpod cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` +Restart multiple pods with given IDs +``` podman pod restart 490eb 3557fb 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` +Restart the last created pod +``` podman pod restart --latest 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` +Restart all pods +``` podman pod restart --all 19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab @@ -42,7 +52,6 @@ podman pod restart --all 70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` - ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-restart(1)](podman-restart.1.md)** diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in index 3655c3938..abcc69e9e 100644 --- a/docs/source/markdown/podman-pod-stop.1.md.in +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -29,20 +29,20 @@ Seconds to wait before forcibly stopping the containers in the pod. ## EXAMPLE -Stop a pod called *mywebserverpod* +Stop pod with a given name ``` $ podman pod stop mywebserverpod cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` -Stop two pods by their short IDs. +Stop multiple pods with given IDs. ``` $ podman pod stop 490eb 3557fb 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab ``` -Stop the most recent pod +Stop the last created pod ``` $ podman pod stop --latest 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab @@ -65,7 +65,7 @@ $ podman pod stop --pod-id-file file1 --pod-id-file file2 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` -Stop all pods with a timeout of 1 second. +Stop all pods with a timeout of 1 second ``` $ podman pod stop -a -t 1 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab diff --git a/docs/source/markdown/podman-rename.1.md b/docs/source/markdown/podman-rename.1.md index 4017db505..0a807e6de 100644 --- a/docs/source/markdown/podman-rename.1.md +++ b/docs/source/markdown/podman-rename.1.md @@ -19,18 +19,18 @@ At present, only containers are supported; pods and volumes cannot be renamed. ## EXAMPLES +Rename container with a given name ``` -# Rename a container by name $ podman rename oldContainer aNewName ``` +Rename container with a given ID ``` -# Rename a container by ID $ podman rename 717716c00a6b testcontainer ``` +Create an alias for container with a given ID ``` -# Use the container rename alias $ podman container rename 6e7514b47180 databaseCtr ``` diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in index c0fa94d82..9eb44dcc1 100644 --- a/docs/source/markdown/podman-rm.1.md.in +++ b/docs/source/markdown/podman-rm.1.md.in @@ -73,37 +73,37 @@ Remove anonymous volumes associated with the container. This does not include na created with **podman volume create**, or the **--volume** option of **podman run** and **podman create**. ## EXAMPLE -Remove a container by its name *mywebserver* +Remove container with a given name ``` $ podman rm mywebserver ``` -Remove a *mywebserver* container and all of the containers that depend on it +Remove container with a given name and all of the containers that depend on it ``` $ podman rm --depend mywebserver ``` -Remove several containers by name and container id. +Remove multiple containers with given names or IDs ``` $ podman rm mywebserver myflaskserver 860a4b23 ``` -Remove several containers reading their IDs from files. +Remove multiple containers with IDs read from files ``` $ podman rm --cidfile ./cidfile-1 --cidfile /home/user/cidfile-2 ``` -Forcibly remove a container by container ID. +Forcibly remove container with a given ID ``` $ podman rm -f 860a4b23 ``` -Remove all containers regardless of its run state. +Remove all containers regardless of the run state ``` $ podman rm -f -a ``` -Forcibly remove the latest container created. +Forcibly remove the last created container ``` $ podman rm -f --latest ``` -- cgit v1.2.3-54-g00ecf From d19438fa6de707290bf12d75ed824491ce2a4aca Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 24 Aug 2022 18:29:16 -0600 Subject: Man pages: refactor common options: --dns-* --dns-opt and --dns-search, but only in podman-create and -run. Went with the -run version in both cases; --dns-opt remained unchanged, but in --dns-search I changed 'and' to 'with'. Did not consolidate podman-build or podman-pod-create: too different. Signed-off-by: Ed Santiago --- docs/source/markdown/options/dns-opt.container.md | 3 +++ docs/source/markdown/options/dns-search.container.md | 4 ++++ docs/source/markdown/podman-create.1.md.in | 8 ++------ docs/source/markdown/podman-run.1.md.in | 9 ++------- 4 files changed, 11 insertions(+), 13 deletions(-) create mode 100644 docs/source/markdown/options/dns-opt.container.md create mode 100644 docs/source/markdown/options/dns-search.container.md (limited to 'docs') diff --git a/docs/source/markdown/options/dns-opt.container.md b/docs/source/markdown/options/dns-opt.container.md new file mode 100644 index 000000000..ea26fd013 --- /dev/null +++ b/docs/source/markdown/options/dns-opt.container.md @@ -0,0 +1,3 @@ +#### **--dns-opt**=*option* + +Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. diff --git a/docs/source/markdown/options/dns-search.container.md b/docs/source/markdown/options/dns-search.container.md new file mode 100644 index 000000000..5a803ba39 --- /dev/null +++ b/docs/source/markdown/options/dns-search.container.md @@ -0,0 +1,4 @@ +#### **--dns-search**=*domain* + +Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_. +Use **--dns-search=.** if you don't wish to set the search domain. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 1ff7429c7..0a880951d 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -184,13 +184,9 @@ is the case the **--dns** flag is necessary for every run. The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. The **/etc/resolv.conf** file in the image will be used without changes. -#### **--dns-opt**=*option* +@@option dns-opt.container -Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is set to 'none' or `container:`. - -#### **--dns-search**=*domain* - -Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to 'none' or `container:`. (Use --dns-search=. if you don't wish to set the search domain) +@@option dns-search.container @@option entrypoint diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index f172ffc9e..6798c65da 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -218,14 +218,9 @@ is the case the **--dns** flag is necessary for every run. The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. The _/etc/resolv.conf_ file in the image will be used without changes. -#### **--dns-opt**=*option* +@@option dns-opt.container -Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. - -#### **--dns-search**=*domain* - -Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to **none** or **container:**_id_. -Use **--dns-search=.** if you don't wish to set the search domain. +@@option dns-search.container @@option entrypoint -- cgit v1.2.3-54-g00ecf