From 557b65e0925ed9f707da60776603a460a77803e9 Mon Sep 17 00:00:00 2001 From: Erik Sjölund Date: Mon, 11 Jul 2022 21:59:32 +0200 Subject: [CI:DOCS] Improve language. Fix spelling and typos. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Correct spelling and typos. * Improve language. Co-authored-by: Ed Santiago Signed-off-by: Erik Sjölund --- docs/source/markdown/podman-run.1.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index e628a806a..a389be2a8 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -288,7 +288,7 @@ detached container with **podman attach**. When attached in the tty mode, you can detach from the container (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. -Configure the keys sequence using the **--detach-keys** option, or specifying +Specify the key sequence using the **--detach-keys** option, or configure it in the **containers.conf** file: see **containers.conf(5)** for more information. #### **--detach-keys**=*sequence* @@ -300,7 +300,7 @@ This option can also be set in **containers.conf**(5) file. #### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] Add a host device to the container. Optional *permissions* parameter -can be used to specify device permissions, it is combination of +can be used to specify device permissions by combining **r** for read, **w** for write, and **m** for **mknod**(2). Example: **--device=/dev/sdc:/dev/xvdc:rwm**. @@ -1158,7 +1158,7 @@ $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image This command mounts a **tmpfs** at _/tmp_ within the container. The supported mount options are the same as the Linux default mount flags. If you do not specify -any options, the systems uses the following options: +any options, the system uses the following options: **rw,noexec,nosuid,nodev**. #### **--tty**, **-t** @@ -1598,7 +1598,7 @@ content. Installing packages into _/usr_, for example. In production, applications seldom need to write to the image. Container applications write to volumes if they need to write to file systems at all. Applications can be made more secure by running them in read-only mode using the **--read-only** switch. -This protects the containers image from modification. Read-only containers may +This protects the container's image from modification. Read-only containers may still need to write temporary data. The best way to handle this is to mount tmpfs directories on _/run_ and _/tmp_. @@ -1879,7 +1879,7 @@ $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello Podman allows for the configuration of storage by changing the values in the _/etc/container/storage.conf_ or by using global options. This -shows how to set up and use fuse-overlayfs for a one time run of busybox +shows how to set up and use fuse-overlayfs for a one-time run of busybox using global options. ``` @@ -1975,7 +1975,7 @@ in the following order of precedence (later entries override earlier entries): - Container image: Any environment variables specified in the container image. - **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details. - **--env-host**: Host environment of the process executing Podman is added. -- **--env-file**: Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. +- **--env-file**: Any environment variables specified via env-files. If multiple files are specified, then they override each other in order of entry. - **--env**: Any environment variables specified will override previous settings. Run containers and set the environment ending with a __*__. -- cgit v1.2.3-54-g00ecf From b29a52a48a9cbe65f47cbdbb618366421ee851b5 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Tue, 12 Jul 2022 14:53:17 -0400 Subject: Docker uses "-c" to mean "--cpu-shares" in create and run Add support for -c as an alias for --cpu-shares to be compatible with Docker. Signed-off-by: Daniel J Walsh --- cmd/podman/common/create.go | 4 ++-- docs/source/markdown/podman-container-clone.1.md | 2 +- docs/source/markdown/podman-create.1.md | 2 +- docs/source/markdown/podman-run.1.md | 2 +- test/e2e/run_cpu_test.go | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/common/create.go b/cmd/podman/common/create.go index 923d0517f..d2646aa43 100644 --- a/cmd/podman/common/create.go +++ b/cmd/podman/common/create.go @@ -849,9 +849,9 @@ func DefineCreateFlags(cmd *cobra.Command, cf *entities.ContainerCreateOptions, _ = cmd.RegisterFlagCompletionFunc(cpuRtRuntimeFlagName, completion.AutocompleteNone) cpuSharesFlagName := "cpu-shares" - createFlags.Uint64Var( + createFlags.Uint64VarP( &cf.CPUShares, - cpuSharesFlagName, 0, + cpuSharesFlagName, "c", 0, "CPU shares (relative weight)", ) _ = cmd.RegisterFlagCompletionFunc(cpuSharesFlagName, completion.AutocompleteNone) diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md index 6d552db75..c0c8d8631 100644 --- a/docs/source/markdown/podman-container-clone.1.md +++ b/docs/source/markdown/podman-container-clone.1.md @@ -61,7 +61,7 @@ The sum of all runtimes across containers cannot exceed the amount allotted to t This option is not supported on cgroups V2 systems. -#### **--cpu-shares**=*shares* +#### **--cpu-shares**, **-c**=*shares* CPU shares (relative weight) diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 09c7d99c1..e7faeb820 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -201,7 +201,7 @@ The sum of all runtimes across containers cannot exceed the amount allotted to t This flag is not supported on cgroups V2 systems. -#### **--cpu-shares**=*shares* +#### **--cpu-shares**, **-c**=*shares* CPU shares (relative weight) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index a389be2a8..547888675 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -220,7 +220,7 @@ The sum of all runtimes across containers cannot exceed the amount allotted to t This flag is not supported on cgroups V2 systems. -#### **--cpu-shares**=*shares* +#### **--cpu-shares**, **-c**=*shares* CPU shares (relative weight). diff --git a/test/e2e/run_cpu_test.go b/test/e2e/run_cpu_test.go index b21be5729..e57eb3b26 100644 --- a/test/e2e/run_cpu_test.go +++ b/test/e2e/run_cpu_test.go @@ -94,7 +94,7 @@ var _ = Describe("Podman run cpu", func() { Expect(result).Should(Exit(0)) Expect(result.OutputToString()).To(Equal("10000")) } else { - result := podmanTest.Podman([]string{"run", "--rm", "--cpu-shares=2", ALPINE, "cat", "/sys/fs/cgroup/cpu/cpu.shares"}) + result := podmanTest.Podman([]string{"run", "--rm", "-c", "2", ALPINE, "cat", "/sys/fs/cgroup/cpu/cpu.shares"}) result.WaitWithDefaultTimeout() Expect(result).Should(Exit(0)) Expect(result.OutputToString()).To(Equal("2")) -- cgit v1.2.3-54-g00ecf From 5f5379deb5520d75f747467c3076919f0297b4bc Mon Sep 17 00:00:00 2001 From: Erik Sjölund Date: Tue, 12 Jul 2022 19:41:20 +0200 Subject: [CI:DOCS] podman-create.md: replace -c with --cpu-shares MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Erik Sjölund --- docs/source/markdown/podman-create.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index e7faeb820..50a90b9ba 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -229,8 +229,8 @@ cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core. For example, consider a system with more than three cores. If you start one -container **{C0}** with **-c=512** running one process, and another container -**{C1}** with **-c=1024** running two processes, this can result in the following +container **{C0}** with **--cpu-shares=512** running one process, and another container +**{C1}** with **--cpu-shares=1024** running two processes, this can result in the following division of CPU shares: PID container CPU CPU share -- cgit v1.2.3-54-g00ecf From d560c789766f9c446c4d222fc5a0e92d86e207e1 Mon Sep 17 00:00:00 2001 From: Erik Sjölund Date: Tue, 12 Jul 2022 19:53:57 +0200 Subject: [CI:DOCS] man pages: replace -c with --cpu-shares MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Erik Sjölund --- docs/source/markdown/podman-container-clone.1.md | 17 +++++++++-------- docs/source/markdown/podman-create.1.md | 19 ++++++++++--------- docs/source/markdown/podman-run.1.md | 14 +++++++------- 3 files changed, 26 insertions(+), 24 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md index c0c8d8631..3b9d79862 100644 --- a/docs/source/markdown/podman-container-clone.1.md +++ b/docs/source/markdown/podman-container-clone.1.md @@ -89,14 +89,15 @@ cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core. For example, consider a system with more than three cores. -container **{C0}** is started with **-c=512** running one process, and another container -**{C1}** with **-c=1024** running two processes, this can result in the following -division of CPU shares: - -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +If the container _C0_ is started with **--cpu-shares=512** running one process, +and another container _C1_ with **--cpu-shares=1024** running two processes, +this can result in the following division of CPU shares: + +| PID | container | CPU | CPU share | +| ---- | ----------- | ------- | ------------ | +| 100 | C0 | 0 | 100% of CPU0 | +| 101 | C1 | 1 | 100% of CPU1 | +| 102 | C1 | 2 | 100% of CPU2 | If none are specified, the original container's CPU shares are used. diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 50a90b9ba..3daa72a74 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -228,15 +228,16 @@ On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core. -For example, consider a system with more than three cores. If you start one -container **{C0}** with **--cpu-shares=512** running one process, and another container -**{C1}** with **--cpu-shares=1024** running two processes, this can result in the following -division of CPU shares: - -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +For example, consider a system with more than three cores. +If the container _C0_ is started with **--cpu-shares=512** running one process, +and another container _C1_ with **--cpu-shares=1024** running two processes, +this can result in the following division of CPU shares: + +| PID | container | CPU | CPU share | +| ---- | ----------- | ------- | ------------ | +| 100 | C0 | 0 | 100% of CPU0 | +| 101 | C1 | 1 | 100% of CPU1 | +| 102 | C1 | 2 | 100% of CPU2 | #### **--cpus**=*number* diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 547888675..b9ab7e5e2 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -244,16 +244,16 @@ On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core. -For example, consider a system with more than three cores. If you start one -container **{C0}** with **--cpu-shares=512** running one process, and another container -**{C1}** with **--cpu-shares=1024** running two processes, this can result in the following -division of CPU shares: +For example, consider a system with more than three cores. +If the container _C0_ is started with **--cpu-shares=512** running one process, +and another container _C1_ with **--cpu-shares=1024** running two processes, +this can result in the following division of CPU shares: | PID | container | CPU | CPU share | | ---- | ----------- | ------- | ------------ | -| 100 | {C0} | 0 | 100% of CPU0 | -| 101 | {C1} | 1 | 100% of CPU1 | -| 102 | {C1} | 2 | 100% of CPU2 | +| 100 | C0 | 0 | 100% of CPU0 | +| 101 | C1 | 1 | 100% of CPU1 | +| 102 | C1 | 2 | 100% of CPU2 | #### **--cpus**=*number* -- cgit v1.2.3-54-g00ecf From a4bae330a5bc76219598ffb25db7331705ff1cdd Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Wed, 13 Jul 2022 10:53:50 -0400 Subject: Add podman events -f to be alias for --filter Needed for Docker compatibility. Signed-off-by: Daniel J Walsh --- cmd/podman/system/events.go | 2 +- docs/source/markdown/podman-events.1.md | 4 ++-- test/system/090-events.bats | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/system/events.go b/cmd/podman/system/events.go index 09e589d3c..b04668f86 100644 --- a/cmd/podman/system/events.go +++ b/cmd/podman/system/events.go @@ -46,7 +46,7 @@ func init() { flags := eventsCommand.Flags() filterFlagName := "filter" - flags.StringArrayVar(&eventOptions.Filter, filterFlagName, []string{}, "filter output") + flags.StringArrayVarP(&eventOptions.Filter, filterFlagName, "f", []string{}, "filter output") _ = eventsCommand.RegisterFlagCompletionFunc(filterFlagName, common.AutocompleteEventFilter) formatFlagName := "format" diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 5d5199e66..526a7fa10 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -77,7 +77,7 @@ The *volume* type will report the following statuses: ## OPTIONS -#### **--filter**=*filter* +#### **--filter**, **-f**=*filter* Filter events that are displayed. They must be in the format of "filter=value". The following filters are supported: @@ -129,7 +129,7 @@ $ podman events Show only Podman create events ``` -$ podman events --filter event=create +$ podman events -f event=create 2019-03-02 10:36:01.375685062 -0600 CST container create 20dc581f6fbf (image=docker.io/library/alpine:latest, name=sharp_morse) 2019-03-02 10:36:08.561188337 -0600 CST container create 58e7e002344c (image=k8s.gcr.io/pause:3.1, name=3e701f270d54-infra) 2019-03-02 10:36:13.146899437 -0600 CST volume create cad6dc50e087 (image=, name=cad6dc50e0879568e7d656bd004bd343d6035e7fc4024e1711506fe2fd459e6f) diff --git a/test/system/090-events.bats b/test/system/090-events.bats index 128802360..ceb53ae73 100644 --- a/test/system/090-events.bats +++ b/test/system/090-events.bats @@ -13,11 +13,11 @@ load helpers run_podman run --label $labelname=$labelvalue --name $cname --rm $IMAGE ls expect=".* container start [0-9a-f]\+ (image=$IMAGE, name=$cname,.* ${labelname}=${labelvalue}" - run_podman events --filter type=container --filter container=$cname --filter label=${labelname}=${labelvalue} --filter event=start --stream=false + run_podman events --filter type=container -f container=$cname --filter label=${labelname}=${labelvalue} --filter event=start --stream=false is "$output" "$expect" "filtering by container name and label" # Same thing, but without the container-name filter - run_podman events --filter type=container --filter label=${labelname}=${labelvalue} --filter event=start --stream=false + run_podman events -f type=container --filter label=${labelname}=${labelvalue} --filter event=start --stream=false is "$output" "$expect" "filtering just by label" # Now filter just by container name, no label -- cgit v1.2.3-54-g00ecf From 52850ce7049277df028fc8839ab99a15be08ead1 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 12 Jul 2022 10:55:23 -0600 Subject: man page checker: enforce stricter options format Followup to #14906, in which a nonexistent option was found in a man page. The xref script was designed to catch that, but I was too lax in my parsing: the option was documented using wrong syntax, and the script didn't catch it. Solution: do not allow *any* unrecognized cruft in the option description lines. And fix all improperly-written entries to conform to the rule: **--option**=*value(s)* Two asterisks around option, which must have two dashes. One asterisk around value(s). This is going to cause headaches for some people adding new options, but I don't think I can fix that: there are many factors that make an unparseable line. Adding 'hint' code would make the script even more complex than it is. I have to assume that our contributors are smart enough to look at surrounding context and figure out the right way to specify options. Signed-off-by: Ed Santiago Signed-off-by: Matthew Heon --- docs/MANPAGE_SYNTAX.md | 6 +- docs/source/markdown/podman-build.1.md | 49 +++++++------- docs/source/markdown/podman-commit.1.md | 2 +- docs/source/markdown/podman-create.1.md | 43 ++++++------ docs/source/markdown/podman-generate-kube.1.md | 2 +- docs/source/markdown/podman-generate-systemd.1.md | 4 +- docs/source/markdown/podman-image-trust.1.md | 4 +- docs/source/markdown/podman-images.1.md | 6 +- docs/source/markdown/podman-import.1.md | 2 +- docs/source/markdown/podman-info.1.md | 2 +- docs/source/markdown/podman-machine-info.1.md | 2 +- docs/source/markdown/podman-machine-init.1.md | 2 +- docs/source/markdown/podman-machine-set.1.md | 2 +- docs/source/markdown/podman-manifest-add.1.md | 2 +- docs/source/markdown/podman-manifest-annotate.1.md | 2 +- docs/source/markdown/podman-network-create.1.md | 2 +- docs/source/markdown/podman-play-kube.1.md | 4 +- docs/source/markdown/podman-pod-clone.1.md | 14 ++-- docs/source/markdown/podman-pod-create.1.md | 24 +++---- docs/source/markdown/podman-pod-inspect.1.md | 2 +- docs/source/markdown/podman-push.1.md | 4 +- docs/source/markdown/podman-run.1.md | 78 +++++++++++----------- docs/source/markdown/podman-stats.1.md | 2 +- .../markdown/podman-system-connection-add.1.md | 6 +- .../markdown/podman-system-connection-remove.1.md | 2 +- docs/source/markdown/podman-volume-create.1.md | 4 +- docs/source/markdown/podman-volume-inspect.1.md | 2 +- docs/source/markdown/podman-volume-ls.1.md | 2 +- hack/xref-helpmsgs-manpages | 47 +++++++++++-- 29 files changed, 182 insertions(+), 141 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/MANPAGE_SYNTAX.md b/docs/MANPAGE_SYNTAX.md index 7fff167ba..60bffdace 100644 --- a/docs/MANPAGE_SYNTAX.md +++ b/docs/MANPAGE_SYNTAX.md @@ -60,15 +60,15 @@ Example sentence: Use **[podman-generate-systemd --new](./source/markdown/podman #### **--version**, **-v** -OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If the arguments behind the OPTION are boolean, it is not shown behind the OPTION itself. The default boolean argument is shown in the same way normal default arguments are displayed.\ +OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If OPTION is boolean, *true/false* are not enumerated. The default boolean argument is shown in the same way normal default arguments are displayed.\ Example: The default is **false**.\ *IMPORTANT: This OPTION is not available with the remote Podman client.* #### **--exit** -An example of an OPTION that has only one possible structure. Thus, it cannot be executed by the extension **-e**. +An example of a boolean OPTION that is only available in long form. -#### **--answer**=, **-a**=**active** | *disable* +#### **--answer**, **-a**=**active** | *disable* The **--answer** OPTION above is an example of an OPTION that accepts two possible arguments as inputs. If a default argument is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used, it must include an argument afterward. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them.\ The default value is shown as **active**. diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index bf710022e..ba7081ff5 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -259,7 +259,7 @@ keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise. -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the container. Optional *permissions* parameter can be used to specify device permissions, it is combination of @@ -267,13 +267,13 @@ can be used to specify device permissions, it is combination of Example: **--device=/dev/sdc:/dev/xvdc:rwm**. -Note: if _host_device_ is a symbolic link then it will be resolved first. +Note: if *host-device* is a symbolic link then it will be resolved first. The container will only store the major and minor numbers of the host device. Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. The **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)** runtime offers a workaround for this by adding the option -#### **--annotation run.oci.keep_original_groups=1**. +**--annotation run.oci.keep_original_groups=1**. #### **--disable-compression**, **-D** @@ -311,7 +311,7 @@ Set custom DNS options to be used during the build. Set custom DNS search domains to be used during the build. -#### **--env** *env[=value]* +#### **--env**=*env[=value]* Add a value (e.g. env=*value*) to the built image. Can be used multiple times. If neither `=` nor a `*value*` are specified, but *env* is set in the current @@ -430,7 +430,7 @@ specified file instead of to standard output and standard error. This option is not supported on the remote client, including Mac and Windows (excluding WSL2) machines. -#### **--logsplit** *bool-value* +#### **--logsplit**=*bool-value* If `--logfile` and `--platform` are specified, the `--logsplit` option allows end-users to split the log file for each platform into different files in the @@ -438,7 +438,7 @@ following format: `${logfile}_${platform-os}_${platform-arch}`. This option is not supported on the remote client, including Mac and Windows (excluding WSL2) machines. -#### **--manifest** "manifest" +#### **--manifest**=*manifest* Name of the manifest list to which the image will be added. Creates the manifest list if it does not exist. This option is useful for building multi architecture images. @@ -507,7 +507,7 @@ 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. -#### **--os-feature** *feature* +#### **--os-feature**=*feature* Set the name of a required operating system *feature* for the image which will be built. By default, if the image is not based on *scratch*, the base image's @@ -517,7 +517,7 @@ is typically only meaningful when the image's OS is Windows. If *feature* has a trailing `-`, then the *feature* is removed from the set of required features which will be listed in the image. -#### **--os-version** *version* +#### **--os-version**=*version* Set the exact required operating system *version* for the image which will be built. By default, if the image is not based on *scratch*, the base image's @@ -525,7 +525,7 @@ required OS version is kept, if the base image specified one. This option is typically only meaningful when the image's OS is Windows, and is typically set in Windows base images, so using this option is usually unnecessary. -#### **--output**, **-o**="" +#### **--output**, **-o**=*output-opts* Output destination (format: type=local,dest=path) @@ -553,9 +553,9 @@ that the PID namespace in which `podman` itself is being run should be reused, or it can be the path to a PID namespace which is already in use by another process. -#### **--platform**="OS/ARCH[/VARIANT][,...]" +#### **--platform**=*os/arch[/variant][,...]* -Set the OS/ARCH of the built image (and its base image, if your build uses one) +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 @@ -566,8 +566,8 @@ comma-separated list of values as its argument. When more than one platform is specified, the `--manifest` option should be used instead of the `--tag` option. -OS/ARCH pairs are those used by the Go Programming Language. In several cases -the ARCH value for a platform differs from one produced by other tools such as +Os/arch pairs are those used by the Go Programming Language. In several cases +the *arch* value for a platform differs from one produced by other tools such as the `arch` command. Valid OS and architecture name combinations are listed as values for $GOOS and $GOARCH at https://golang.org/doc/install/source#environment, and can also be found by running `go tool dist list`. @@ -576,7 +576,7 @@ While `podman build` is happy to use base images and build images for any platform that exists, `RUN` instructions will not be able to succeed without the help of emulation provided by packages like `qemu-user-static`. -#### **--pull**=**always**|**missing**|**never**|**newer** +#### **--pull**=*policy* Pull image policy. The default is **always**. @@ -655,7 +655,7 @@ layers are not squashed. Squash all of the new image's layers (including those inherited from a base image) into a single new layer. -#### **--ssh**=*default|id[=socket>|[,]* +#### **--ssh**=*default* | *id[=socket>* SSH agent socket or keys to expose to the build. The socket path can be left empty to use the value of `default=$SSH_AUTH_SOCK` @@ -683,7 +683,7 @@ Set the target build stage to build. When building a Containerfile with multiple build stages, --target can be used to specify an intermediate build stage by name as the final stage for the resulting image. Commands after the target stage will be skipped. -#### **--timestamp** *seconds* +#### **--timestamp**=*seconds* Set the create timestamp to seconds since epoch to allow for deterministic builds (defaults to current time). By default, the created timestamp is changed @@ -699,7 +699,7 @@ timestamp. Require HTTPS and verify certificates when talking to container registries (defaults to true). (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--ulimit**=*type*=*soft-limit*[:*hard-limit*] +#### **--ulimit**=*type=soft-limit[:hard-limit]* Specifies resource limits to apply to processes launched when processing `RUN` instructions. This option can be specified multiple times. Recognized resource @@ -720,7 +720,7 @@ types include: "sigpending": maximum number of pending signals (ulimit -i) "stack": maximum stack size (ulimit -s) -#### **--unsetenv** *env* +#### **--unsetenv**=*env* Unset environment variables from the final image. @@ -814,19 +814,20 @@ that the UTS namespace in which `podman` itself is being run should be reused, or it can be the path to a UTS namespace which is already in use by another process. -#### **--variant**="" +#### **--variant**=*variant* Set the architecture variant 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 variant of the build host. -#### **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]* - Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman - bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman - container. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +Create a bind mount. If you specify `-v /HOST-DIR:/CONTAINER-DIR`, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. (This option is not available with the remote Podman client, +including Mac and Windows (excluding WSL2) machines) - The `OPTIONS` are a comma-separated list and can be: [[1]](#Footnote1) +The `OPTIONS` are a comma-separated list and can be: [[1]](#Footnote1) * [rw|ro] * [z|Z|O] diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md index 3df931254..b7b52e3a7 100644 --- a/docs/source/markdown/podman-commit.1.md +++ b/docs/source/markdown/podman-commit.1.md @@ -36,7 +36,7 @@ Apply the following possible instructions to the created image: Can be set multiple times. -#### **--format**, **-f** =**oci** | *docker* +#### **--format**, **-f**=**oci** | *docker* Set the format of the image manifest and metadata. The currently supported formats are **oci** and *docker*.\ The default is **oci**. diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 3daa72a74..67bb573e2 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -243,7 +243,7 @@ this can result in the following division of CPU shares: 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**. +**--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 @@ -261,7 +261,7 @@ If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` then processes in your container will only use memory from the first two memory nodes. -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the container. Optional *permissions* parameter can be used to specify device permissions, it is combination of @@ -269,7 +269,7 @@ can be used to specify device permissions, it is combination of Example: **--device=/dev/sdc:/dev/xvdc:rwm**. -Note: if _host_device_ is a symbolic link then it will be resolved first. +Note: if *host-device* is a symbolic link then it will be resolved first. The container will only store the major and minor numbers of the host device. Note: if the user only has access rights via a group, accessing the device @@ -280,7 +280,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" +#### **--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); @@ -376,7 +376,7 @@ __--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. -#### **--group-add**=*group|keep-groups* +#### **--group-add**=*group* | *keep-groups* Assign additional groups to the primary user running within the container process. @@ -419,7 +419,7 @@ value can be expressed in a time format such as `1m22s`. The default value is `3 Print usage statement -#### **--hostname**=*name*, **-h** +#### **--hostname**, **-h**=*name* Container host name @@ -450,7 +450,7 @@ container: Defaults to `true` -#### **--image-volume**, **builtin-volume**=*bind|tmpfs|ignore* +#### **--image-volume**=**bind** | *tmpfs* | *ignore* Tells Podman how to handle the builtin image volumes. Default is **bind**. @@ -465,8 +465,9 @@ Run an init inside the container that forwards signals and reaps processes. The container-init binary is mounted at `/run/podman-init`. Mounting over `/run` will hence break container execution. -#### **--init-ctr**=*type* (pods only) +#### **--init-ctr**=*type* +(Pods only). When using pods, create an init style container, which is run after the infra container is started but before regular pod containers are started. Init containers are useful for running setup operations for the pod's applications. @@ -531,7 +532,7 @@ Read in a line delimited file of labels Not implemented -#### **--log-driver**="*k8s-file*" +#### **--log-driver**=*driver* Logging driver for the container. Currently available options are *k8s-file*, *journald*, *none* and *passthrough*, with *json-file* aliased to *k8s-file* for scripting compatibility. @@ -544,7 +545,7 @@ The *passthrough* driver passes down the standard streams (stdin, stdout, stderr container. It is not allowed with the remote Podman client, including Mac and Windows (excluding WSL2) machines, and on a tty, since it is vulnerable to attacks via TIOCSTI. -#### **--log-opt**=*name*=*value* +#### **--log-opt**=*name=value* Set custom logging configuration. The following *name*s are supported: @@ -828,11 +829,11 @@ container. Rootless containers cannot have more privileges than the account that launched them. -#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_] +#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* Publish a container's port, or range of ports, to the host. -Both hostPort and containerPort can be specified as a range of ports. +Both *hostPort* and *containerPort* can be specified as a range of ports. When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. @@ -868,7 +869,7 @@ port to a random port on the host within an *ephemeral port range* defined by `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host ports and the exposed ports, use `podman port`. -#### **--pull**=**always**|**missing**|**never**|**newer** +#### **--pull**=*policy* Pull image policy. The default is **missing**. @@ -897,7 +898,7 @@ If container is running in --read-only mode, then mount a read-write tmpfs on /r If another container with the same name already exists, replace and remove it. The default is **false**. -#### **--requires**=**container** +#### **--requires**=*container* Specify one or more requirements. A requirement is a dependency container that will be started before this container. @@ -940,7 +941,7 @@ directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. -#### **--sdnotify**=**container**|**conmon**|**ignore** +#### **--sdnotify**=**container** | *conmon* | *ignore* Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. @@ -957,7 +958,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will Note that this feature is experimental and may change in the future. -#### **--secret**=*secret*[,opt=opt ...] +#### **--secret**=*secret[,opt=opt ...]* Give the container access to a secret. Can be specified multiple times. @@ -1052,7 +1053,7 @@ Network Namespace - current sysctls allowed: Note: if you use the --network=host option these sysctls will not be allowed. -#### **--systemd**=*true|false|always* +#### **--systemd**=*true* | *false* | *always* Run container in systemd mode. The default is *true*. @@ -1120,7 +1121,7 @@ standard input. Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. Remote connections use local containers.conf for defaults -#### **--uidmap**=*container_uid*:*from_uid*:*amount* +#### **--uidmap**=*container_uid:from_uid:amount* Run the container in a new user namespace using the supplied UID mapping. This option conflicts with the **--userns** and **--subuidname** options. This @@ -1215,7 +1216,7 @@ Unset default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables configured by the image, and environment variables from containers.conf. -#### **--unsetenv-all**=*true|false* +#### **--unsetenv-all** Unset all default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables @@ -1285,7 +1286,7 @@ Set the UTS namespace mode for the container. The following values are supported #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman @@ -1455,7 +1456,7 @@ Note: if the user only has access rights via a group, accessing the volume from inside a rootless container will fail. Use the `--group-add keep-groups` flag to pass the user's supplementary group access into the container. -#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]] +#### **--volumes-from**=*CONTAINER[:OPTIONS]]* Mount volumes from the specified container(s). Used to share volumes between containers. The *options* is a comma-separated list with the following available elements: diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md index cbb875f60..2ba0a7175 100644 --- a/docs/source/markdown/podman-generate-kube.1.md +++ b/docs/source/markdown/podman-generate-kube.1.md @@ -30,7 +30,7 @@ Note that the generated Kubernetes YAML file can be used to re-run the deploymen ## OPTIONS -#### **--filename**, **-f**=**filename** +#### **--filename**, **-f**=*filename* Output to the given file, instead of STDOUT. If the file already exists, `generate kube` will refuse to replace it and return an error. diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index 56ad4e446..f61fa4523 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -83,11 +83,11 @@ Takes a value in seconds. Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is *-*. -#### **--start-timeout** =*value* +#### **--start-timeout**=*value* Override the default start timeout for the container with the given value in seconds. -#### **--stop-timeout** =*value* +#### **--stop-timeout**=*value* Override the default stop timeout for the container with the given value in seconds. diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 66d492922..4e80bdcf5 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -42,12 +42,12 @@ Trust may be updated using the command **podman image trust set** for an existin ### set OPTIONS -#### **--pubkeysfile**=*KEY1*, **-f** +#### **--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. -#### **--type**=*value*, **-t** +#### **--type**, **-t**=*value* The trust type for this policy entry. Accepted values: **signedBy** (default): Require signatures with corresponding list of diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index e28df840d..923b22f1b 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -23,7 +23,7 @@ Show all images (by default filter out the intermediate image layers). The defau Show image digests -#### **--filter**=*filter*, **-f** +#### **--filter**, **-f**=*filter* Provide filter values. @@ -100,9 +100,9 @@ Omit the table headings from the listing of images. Lists only the image IDs. -#### **--sort**=*sort*=*created* +#### **--sort**=*sort* -Sort by created, id, repository, size or tag (default: created) +Sort by *created*, *id*, *repository*, *size* or *tag* (default: **created**) ## EXAMPLE diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index bfe0291de..4002f5255 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -23,7 +23,7 @@ Note: `:` is a restricted character and cannot be part of the file name. Set architecture of the imported image. -#### **--change**=*instruction*, **-c** +#### **--change**, **-c**=*instruction* Apply the following possible instructions to the created image: **CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR** diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index 28e4f3291..347d8d27b 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -19,7 +19,7 @@ Displays information pertinent to the host, current storage stats, configured co Show additional information -#### **--format**=*format*, **-f** +#### **--format**, **-f**=*format* Change output format to "json" or a Go template. diff --git a/docs/source/markdown/podman-machine-info.1.md b/docs/source/markdown/podman-machine-info.1.md index 33c207d32..926d3d8b3 100644 --- a/docs/source/markdown/podman-machine-info.1.md +++ b/docs/source/markdown/podman-machine-info.1.md @@ -13,7 +13,7 @@ Rootless only, as all `podman machine` commands can be only be used with rootles ## OPTIONS -#### **--format**=*format*, **-f** +#### **--format**, **-f**=*format* Change output format to "json" or a Go template. diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md index 21c98b2c7..07273a111 100644 --- a/docs/source/markdown/podman-machine-init.1.md +++ b/docs/source/markdown/podman-machine-init.1.md @@ -62,7 +62,7 @@ Memory (in MB). Start the virtual machine immediately after it has been initialized. -#### **--rootful**=*true|false* +#### **--rootful** Whether this machine should prefer rootful (`true`) or rootless (`false`) container execution. This option will also determine the remote connection default diff --git a/docs/source/markdown/podman-machine-set.1.md b/docs/source/markdown/podman-machine-set.1.md index 1daf97a61..52338cedb 100644 --- a/docs/source/markdown/podman-machine-set.1.md +++ b/docs/source/markdown/podman-machine-set.1.md @@ -33,7 +33,7 @@ Print usage statement. Memory (in MB). Only supported for QEMU machines. -#### **--rootful**=*true|false* +#### **--rootful** Whether this machine should prefer rootful (`true`) or rootless (`false`) container execution. This option will also update the current podman diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md index 40f841bf8..5aa7f8341 100644 --- a/docs/source/markdown/podman-manifest-add.1.md +++ b/docs/source/markdown/podman-manifest-add.1.md @@ -22,7 +22,7 @@ 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* +#### **--annotation**=*annotation=value* Set an annotation on the entry for the newly-added image. diff --git a/docs/source/markdown/podman-manifest-annotate.1.md b/docs/source/markdown/podman-manifest-annotate.1.md index 2b8b70aa4..36c35c7c8 100644 --- a/docs/source/markdown/podman-manifest-annotate.1.md +++ b/docs/source/markdown/podman-manifest-annotate.1.md @@ -12,7 +12,7 @@ Adds or updates information about an image included in a manifest list or image ## OPTIONS -#### **--annotation** *annotation=value* +#### **--annotation**=*annotation=value* Set an annotation on the entry for the specified image. diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 1d89b12e3..3587ac2a8 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -67,7 +67,7 @@ Enable IPv6 (Dual Stack) networking. If not subnets are given it will allocate a Set metadata for a network (e.g., --label mykey=value). -#### **--opt**=*option*, **-o** +#### **--opt**, **-o**=*option* Set driver specific options. diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 92cb694b0..47e438bd6 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -170,11 +170,11 @@ Print usage statement Assign a static ip address to the pod. This option can be specified several times when play kube creates more than one pod. Note: When joining multiple networks you should use the **--network name:ip=\** syntax. -#### **--log-driver**=driver +#### **--log-driver**=*driver* Set logging driver for all created containers. -#### **--log-opt**=*name*=*value* +#### **--log-opt**=*name=value* Set custom logging configuration. The following *name*s are supported: diff --git a/docs/source/markdown/podman-pod-clone.1.md b/docs/source/markdown/podman-pod-clone.1.md index d90d1efb9..49084386c 100644 --- a/docs/source/markdown/podman-pod-clone.1.md +++ b/docs/source/markdown/podman-pod-clone.1.md @@ -27,7 +27,7 @@ CPUs in which to allow execution (0-3, 0,1). If none are specified, the original Remove the original pod that we are cloning once used to mimic the configuration. -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the pod. Optional *permissions* parameter can be used to specify device permissions. It is a combination of @@ -56,7 +56,7 @@ GID map for the user namespace. Using this flag will run all containers in the p Print usage statement. -#### **--hostname**=name +#### **--hostname**=*name* Set a hostname to the pod. @@ -72,7 +72,7 @@ Write the pid of the infra container's **conmon** process to a file. As **conmon The name that will be used for the pod's infra container. -#### **--label**=*label*, **-l** +#### **--label**, **-l**=*label* Add metadata to a pod (e.g., --label com.example.key=value). @@ -153,7 +153,7 @@ Name for GID map from the `/etc/subgid` file. Using this flag will run the conta Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. -#### **--sysctl**=_name_=_value_ +#### **--sysctl**=*name=value* Configure namespace kernel parameters for all containers in the new pod. @@ -175,7 +175,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed. Note: if the network namespace is not shared within the pod, these sysctls are not allowed. -#### **--uidmap**=*container_uid*:*from_uid*:*amount* +#### **--uidmap**=*container_uid:from_uid:amount* Run all containers in the pod in a new user namespace using the supplied mapping. This option conflicts with the **--userns** and **--subuidname** options. This @@ -220,7 +220,7 @@ Set the UTS namespace mode for the pod. The following values are supported: - **ns:[path]**: run the pod in the given existing UTS namespace. -#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* Create a bind mount. If ` -v /HOST-DIR:/CONTAINER-DIR` is specified, Podman bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman @@ -381,7 +381,7 @@ change propagation properties of source mount. Say `/` is source mount for Note: if the user only has access rights via a group, accessing the volume from inside a rootless pod will fail. -#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]] +#### **--volumes-from**=*container[:options]]* Mount volumes from the specified container(s). Used to share volumes between containers and pods. The *options* is a comma-separated list with the following available elements: diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index 53d1e3327..bd2421cdf 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -25,7 +25,7 @@ for it. The name is useful any place you need to identify a pod. ## OPTIONS -#### **--add-host**=_host_:_ip_ +#### **--add-host**=*host:ip* Add a custom host-to-IP mapping (host:ip) @@ -52,7 +52,7 @@ Examples of the List Format: 0-4,9 # bits 0, 1, 2, 3, 4, and 9 set 0-2,7,12-14 # bits 0, 1, 2, 7, 12, 13, and 14 set -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the pod. Optional *permissions* parameter can be used to specify device permissions. It is a combination of @@ -60,7 +60,7 @@ can be used to specify device permissions. It is a combination of Example: **--device=/dev/sdc:/dev/xvdc:rwm**. -Note: if _host_device_ is a symbolic link then it will be resolved first. +Note: if *host-device* is a symbolic link then it will be resolved first. The pod will only store the major and minor numbers of the host device. Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod. @@ -102,7 +102,7 @@ GID map for the user namespace. Using this flag will run the container with user Print usage statement. -#### **--hostname**=name +#### **--hostname**=*name* Set a hostname to the pod @@ -144,7 +144,7 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per pod, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--label**=*label*, **-l** +#### **--label**, **-l**=*label* Add metadata to a pod (e.g., --label com.example.key=value). @@ -175,7 +175,7 @@ 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). -#### **--name**=*name*, **-n** +#### **--name**, **-n**=*name* Assign a name to the pod. @@ -237,11 +237,11 @@ Set the PID mode for the pod. The default is to create a private PID namespace f Write the pod ID to the file. -#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_] +#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* Publish a container's port, or range of ports, within this pod to the host. -Both hostPort and containerPort can be specified as a range of ports. +Both *hostPort* and *containerPort* can be specified as a range of ports. When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. @@ -323,7 +323,7 @@ Name for GID map from the `/etc/subgid` file. Using this flag will run the conta Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. -#### **--sysctl**=_name_=_value_ +#### **--sysctl**=*name=value* Configure namespace kernel parameters for all containers in the pod. @@ -345,7 +345,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed. Note: if the network namespace is not shared within the pod, these sysctls are not allowed. -#### **--uidmap**=*container_uid*:*from_uid*:*amount* +#### **--uidmap**=*container_uid:from_uid:amount* Run the container in a new user namespace using the supplied mapping. This option conflicts with the **--userns** and **--subuidname** options. This @@ -389,7 +389,7 @@ Set the UTS namespace mode for the pod. The following values are supported: - **private**: create a new namespace for the pod (default). - **ns:[path]**: run the pod in the given existing UTS namespace. -#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman @@ -548,7 +548,7 @@ change propagation properties of source mount. Say `/` is source mount for Note: if the user only has access rights via a group, accessing the volume from inside a rootless pod will fail. -#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]] +#### **--volumes-from**=*container[:options]]* Mount volumes from the specified container(s). Used to share volumes between containers and pods. The *options* is a comma-separated list with the following available elements: diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index 3105ebaab..d0a165b05 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -12,7 +12,7 @@ that belong to the pod. ## OPTIONS -#### **--format**=*format*, **-f** +#### **--format**, **-f**=*format* Change the default output format. This can be of a supported type like 'json' or a Go template. diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index 25c1e024a..3cda982ac 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -65,7 +65,7 @@ Please refer to containers-certs.d(5) for details. (This option is not available 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** *COMPRESSION* +#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip`. @@ -75,7 +75,7 @@ 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* +#### **--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) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index b9ab7e5e2..4566a73d0 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -83,14 +83,14 @@ and specified with a _tag_. $ podman run oci-archive:/tmp/fedora echo hello ## OPTIONS -#### **--add-host**=_host_:_ip_ +#### **--add-host**=*host:ip* Add a custom host-to-IP mapping (host:ip) Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times. -#### **--annotation**=_key_=_value_ +#### **--annotation**=*key=value* Add an annotation to the container. This option can be set multiple times. @@ -98,7 +98,7 @@ This option can be set multiple times. #### **--arch**=*ARCH* Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`. -#### **--attach**, **-a**=**stdin**|**stdout**|**stderr** +#### **--attach**, **-a**=*stdin* | *stdout* | *stderr* Attach to STDIN, STDOUT or STDERR. @@ -109,7 +109,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*] +#### **--authfile**=*[path]* Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. @@ -120,7 +120,7 @@ environment variable. Block IO relative weight. The _weight_ is a value between **10** and **1000**. -#### **--blkio-weight-device**=*device*:*weight* +#### **--blkio-weight-device**=*device:weight* Block IO relative device weight. @@ -151,7 +151,7 @@ Set the cgroup namespace mode for the container. If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**. -#### **--cgroups**=**enabled**|**disabled**|**no-conmon**|**split** +#### **--cgroups**=*how* Determines whether the container will create CGroups. @@ -259,7 +259,7 @@ this can result in the following division of CPU shares: 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**. +**--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 @@ -297,7 +297,7 @@ Specify the key sequence for detaching a container. Format is a single character This option can also be set in **containers.conf**(5) file. -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the container. Optional *permissions* parameter can be used to specify device permissions by combining @@ -316,23 +316,23 @@ 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 +#### **--device-cgroup-rule**=*rule* Add a rule to the cgroup allowed devices list -#### **--device-read-bps**=_path_:_rate_ +#### **--device-read-bps**=*path:rate* Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). -#### **--device-read-iops**=_path_:_rate_ +#### **--device-read-iops**=*path:rate* Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). -#### **--device-write-bps**=_path_:_rate_ +#### **--device-write-bps**=*path:rate* Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**). -#### **--device-write-iops**=_path_:_rate_ +#### **--device-write-iops**=*path:rate* Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). @@ -402,7 +402,7 @@ Use host environment inside of the container. See **Environment** note below for Expose a port, or a range of ports (e.g. **--expose=3300-3310**) to set up port redirection on the host system. -#### **--gidmap**=*container_gid*:*host_gid*:*amount* +#### **--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 @@ -411,7 +411,7 @@ __--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. -#### **--group-add**=*group|keep-groups* +#### **--group-add**=*group* | *keep-groups* Assign additional groups to the primary user running within the container process. @@ -454,7 +454,7 @@ value can be expressed in a time format such as **1m22s**. The default value is Print usage statement -#### **--hostname**=*name*, **-h** +#### **--hostname**, **-h**=*name* Container host name @@ -480,7 +480,7 @@ proxy environment at container build time.) (This option is not available with t Defaults to **true**. -#### **--image-volume**, **builtin-volume**=**bind**|**tmpfs**|**ignore** +#### **--image-volume**=**bind** | *tmpfs* | *ignore* Tells Podman how to handle the builtin image volumes. Default is **bind**. @@ -534,7 +534,7 @@ a private IPC namespace. - **private**: private IPC namespace. = **shareable**: private IPC namespace with a possibility to share it with other containers. -#### **--label**, **-l**=*key*=*value* +#### **--label**, **-l**=*key=value* Add metadata to a container. @@ -546,9 +546,9 @@ Read in a line-delimited file of labels. Not implemented. -#### **--log-driver**="*driver*" +#### **--log-driver**=*driver* -Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none** and **passthrough**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default journald) +Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none** and **passthrough**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default **journald**) The podman info command below will display the default log-driver for the system. ``` @@ -560,7 +560,7 @@ container. It is not allowed with the remote Podman client, including Mac and W vulnerable to attacks via TIOCSTI. -#### **--log-opt**=*name*=*value* +#### **--log-opt**=*name=value* Logging driver specific options. @@ -589,7 +589,7 @@ according to RFC4862. To specify multiple static MAC addresses per container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option. -#### **--memory**, **-m**=_number_[_unit_] +#### **--memory**, **-m**=*number[unit]* Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). @@ -599,7 +599,7 @@ 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). -#### **--memory-reservation**=_number_[_unit_] +#### **--memory-reservation**=*number[unit]* Memory soft limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). @@ -609,7 +609,7 @@ 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. -#### **--memory-swap**=_number_[_unit_] +#### **--memory-swap**=*number[unit]* A limit value equal to memory plus swap. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). @@ -858,11 +858,11 @@ points, Apparmor/SELinux separation, and Seccomp filters are all disabled. Rootless containers cannot have more privileges than the account that launched them. -#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_] +#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* Publish a container's port, or range of ports, to the host. -Both hostPort and containerPort can be specified as a range of ports. +Both *hostPort* and *containerPort* can be specified as a range of ports. When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. @@ -899,7 +899,7 @@ When using this option, Podman will bind any exposed port to a random port on th within an ephemeral port range defined by */proc/sys/net/ipv4/ip_local_port_range*. To find the mapping between the host ports and the exposed ports, use **podman port**. -#### **--pull**=**always**|**missing**|**never**|**newer** +#### **--pull**=*policy* Pull image policy. The default is **missing**. @@ -928,7 +928,7 @@ If container is running in **--read-only** mode, then mount a read-write tmpfs o If another container with the same name already exists, replace and remove it. The default is **false**. -#### **--requires**=**container** +#### **--requires**=*container* Specify one or more requirements. A requirement is a dependency container that will be started before this container. @@ -979,7 +979,7 @@ finishes executing, similar to a tmpfs mount point being unmounted. Note: On **SELinux** systems, the rootfs needs the correct label, which is by default **unconfined_u:object_r:container_file_t**. -#### **--sdnotify**=**container**|**conmon**|**ignore** +#### **--sdnotify**=**container** | *conmon* | *ignore* Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. @@ -996,7 +996,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will Note that this feature is experimental and may change in the future. -#### **--secret**=*secret*[,opt=opt ...] +#### **--secret**=*secret[,opt=opt ...]* Give the container access to a secret. Can be specified multiple times. @@ -1051,7 +1051,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file. -#### **--shm-size**=_number_[_unit_] +#### **--shm-size**=*number[unit]* Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**. @@ -1082,7 +1082,7 @@ Run the container in a new user namespace using the map with _name_ in the _/etc If calling **podman run** as an unprivileged user, the user needs to have the right to use the mapping. See **subuid**(5). This flag conflicts with **--userns** and **--uidmap**. -#### **--sysctl**=_name_=_value_ +#### **--sysctl**=*name=value* Configure namespaced kernel parameters at runtime. @@ -1106,7 +1106,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** +#### **--systemd**=*true* | *false* | *always* Run container in systemd mode. The default is **true**. @@ -1180,7 +1180,7 @@ echo "asdf" | podman run --rm -i someimage /bin/cat Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. Remote connections use local containers.conf for defaults -#### **--uidmap**=*container_uid*:*from_uid*:*amount* +#### **--uidmap**=*container_uid:from_uid:amount* Run the container in a new user namespace using the supplied UID mapping. This option conflicts with the **--userns** and **--subuidname** options. This @@ -1275,15 +1275,15 @@ Unset default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables configured by the image, and environment variables from containers.conf. -#### **--unsetenv-all**=*true|false* +#### **--unsetenv-all** Unset all default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables configured by the image, and environment variables from containers.conf. -#### **--user**, **-u**=[_user_ | _user_:_group_ | _uid_ | _uid_:_gid_ | _user_:_gid_ | _uid_:_group_ ] +#### **--user**, **-u**=*user[:group]* -Sets the username or UID used and optionally the groupname or GID for the specified command. +Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric. Without this argument, the command will run as the user specified in the container image. Unless overridden by a `USER` command in the Containerfile or by a value passed to this option, this user generally defaults to root. @@ -1345,7 +1345,7 @@ Set the UTS namespace mode for the container. The following values are supported #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman @@ -1519,7 +1519,7 @@ Note: if the user only has access rights via a group, accessing the volume from inside a rootless container will fail. Use the `--group-add keep-groups` flag to pass the user's supplementary group access into the container. -#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]] +#### **--volumes-from**=*CONTAINER[:OPTIONS]* Mount volumes from the specified container(s). Used to share volumes between containers. The *options* is a comma-separated list with the following available elements: diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index 472cbfbcf..d87da6a60 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -44,7 +44,7 @@ Valid placeholders for the Go template are listed below: When using a GO template, you may precede the format with `table` to print headers. -#### **--interval**=*seconds*, **-i**=*seconds* +#### **--interval**, **-i**=*seconds* Time in seconds between stats reports, defaults to 5 seconds. diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md index 76f222f2b..d608ab7a7 100644 --- a/docs/source/markdown/podman-system-connection-add.1.md +++ b/docs/source/markdown/podman-system-connection-add.1.md @@ -17,9 +17,9 @@ The user will be prompted for the remote ssh login password or key file pass phr ## OPTIONS -#### **--default**=*false*, **-d** +#### **--default**, **-d** -Make the new destination the default for this user. +Make the new destination the default for this user. The default is **false**. #### **--identity**=*path* @@ -27,7 +27,7 @@ Path to ssh identity file. If the identity file has been encrypted, Podman promp If no identity file is provided and no user is given, Podman defaults to the user running the podman command. Podman prompts for the login password on the remote server. -#### **--port**=*port*, **-p** +#### **--port**, **-p**=*port* Port for ssh destination. The default value is `22`. diff --git a/docs/source/markdown/podman-system-connection-remove.1.md b/docs/source/markdown/podman-system-connection-remove.1.md index 4914ac9e9..348b49876 100644 --- a/docs/source/markdown/podman-system-connection-remove.1.md +++ b/docs/source/markdown/podman-system-connection-remove.1.md @@ -11,7 +11,7 @@ Delete named ssh destination. ## OPTIONS -#### **--all**=*false*, **-a** +#### **--all**, **-a** Remove all connections. diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md index f43e647bf..65b788851 100644 --- a/docs/source/markdown/podman-volume-create.1.md +++ b/docs/source/markdown/podman-volume-create.1.md @@ -23,11 +23,11 @@ Specify the volume driver name (default **local**). Setting this to a value othe Print usage statement -#### **--label**=*label*, **-l** +#### **--label**, **-l**=*label* Set metadata for a volume (e.g., --label mykey=value). -#### **--opt**=*option*, **-o** +#### **--opt**, **-o**=*option* Set driver specific options. For the default driver, **local**, this allows a volume to be configured to mount a filesystem on the host. diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md index dda83e558..9be0f9c2d 100644 --- a/docs/source/markdown/podman-volume-inspect.1.md +++ b/docs/source/markdown/podman-volume-inspect.1.md @@ -20,7 +20,7 @@ Volumes can be queried individually by providing their full name or a unique par Inspect all volumes. -#### **--format**=*format*, **-f** +#### **--format**, **-f**=*format* Format volume output using Go template diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md index 4a3489425..86896b0a2 100644 --- a/docs/source/markdown/podman-volume-ls.1.md +++ b/docs/source/markdown/podman-volume-ls.1.md @@ -14,7 +14,7 @@ flag. Use the **--quiet** flag to print only the volume names. ## OPTIONS -#### **--filter**=*filter*, **-f** +#### **--filter**, **-f**=*filter* Volumes can be filtered by the following attributes: diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index 7c07a4f01..de9ef8630 100755 --- a/hack/xref-helpmsgs-manpages +++ b/hack/xref-helpmsgs-manpages @@ -350,7 +350,7 @@ sub podman_man { # This is a while-loop because there may be multiple long # option names, e.g. --net/--network my $is_first = 1; - while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(=\*[a-zA-Z0-9-]+\*)?(,\s+)?//g) { + while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(,\s+)?//g) { my $flag = $1; $man{$flag} = 1; if ($flag lt $previous_flag && $is_first) { @@ -365,11 +365,50 @@ sub podman_man { $is_first = 0; } # Short form - if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*(=\*[a-zA-Z0-9-]+\*)?//g) { - $man{$1} = 1; + if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*//) { + my $flag = $1; + $man{$flag} = 1; # Keep track of them, in case we see 'Not implemented' below - push @most_recent_flags, $1; + push @most_recent_flags, $flag; + } + + # Options with no '=whatever' + next if !$line; + + # Anything remaining *must* be of the form '=' + if ($line !~ /^=/) { + warn "$ME: $subpath:$.: could not parse '$line' in option description\n"; + ++$Errs; + } + + # For some years it was traditional, albeit wrong, to write + # **--foo**=*bar*, **-f** + # The correct way is to add =*bar* at the end. + if ($line =~ s/,\s\*\*(-[a-zA-Z])\*\*//) { + $man{$1} = 1; + warn "$ME: $subpath:$.: please rewrite as ', **$1**$line'\n"; + ++$Errs; + } + + # List of possibilities ('=*a* | *b*') must be space-separated + if ($line =~ /\|/) { + if ($line =~ /[^\s]\|[^\s]/) { + # Sigh, except for this one special case + if ($line !~ /SOURCE-VOLUME.*HOST-DIR.*CONTAINER-DIR/) { + warn "$ME: $subpath:$.: values must be space-separated: '$line'\n"; + ++$Errs; + } + } + my $copy = $line; + if ($copy =~ s/\**true\**//) { + if ($copy =~ s/\**false\**//) { + if ($copy !~ /[a-z]/) { + warn "$ME: $subpath:$.: Do not enumerate true/false for boolean-only options\n"; + ++$Errs; + } + } + } } } } -- cgit v1.2.3-54-g00ecf From 6d84a9952f1e5be1a187bcc6d9bbc2532331cfc8 Mon Sep 17 00:00:00 2001 From: Karthik Elango Date: Tue, 28 Jun 2022 15:31:20 -0400 Subject: Podman stop --filter flag Filter flag is added for podman stop and podman --remote stop. Filtering logic is implemented in getContainersAndInputByContext(). Start filtering can be manipulated to use this logic as well to limit redundancy. Signed-off-by: Karthik Elango --- cmd/podman/containers/stop.go | 17 ++++++++++-- cmd/podman/validate/args.go | 7 +++++ docs/source/markdown/podman-stop.1.md | 24 +++++++++++++++++ pkg/api/handlers/compat/containers_stop.go | 2 -- pkg/domain/entities/containers.go | 1 + pkg/domain/infra/abi/containers.go | 31 +++++++++++++++++----- pkg/domain/infra/tunnel/containers.go | 6 ++--- pkg/domain/infra/tunnel/helpers.go | 14 ++++++---- test/e2e/stop_test.go | 42 ++++++++++++++++++++++++++++++ 9 files changed, 125 insertions(+), 19 deletions(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/containers/stop.go b/cmd/podman/containers/stop.go index 2ddd169a1..261f441c3 100644 --- a/cmd/podman/containers/stop.go +++ b/cmd/podman/containers/stop.go @@ -49,7 +49,9 @@ var ( ) var ( - stopOptions = entities.StopOptions{} + stopOptions = entities.StopOptions{ + Filters: make(map[string][]string), + } stopTimeout uint ) @@ -67,6 +69,10 @@ func stopFlags(cmd *cobra.Command) { flags.UintVarP(&stopTimeout, timeFlagName, "t", containerConfig.Engine.StopTimeout, "Seconds to wait for stop before killing the container") _ = cmd.RegisterFlagCompletionFunc(timeFlagName, completion.AutocompleteNone) + filterFlagName := "filter" + flags.StringSliceVarP(&filters, filterFlagName, "f", []string{}, "Filter output based on conditions given") + _ = cmd.RegisterFlagCompletionFunc(filterFlagName, common.AutocompletePsFilters) + if registry.IsRemote() { _ = flags.MarkHidden("cidfile") _ = flags.MarkHidden("ignore") @@ -97,7 +103,6 @@ func stop(cmd *cobra.Command, args []string) error { if cmd.Flag("time").Changed { stopOptions.Timeout = &stopTimeout } - for _, cidFile := range cidFiles { content, err := ioutil.ReadFile(cidFile) if err != nil { @@ -107,6 +112,14 @@ func stop(cmd *cobra.Command, args []string) error { args = append(args, id) } + for _, f := range filters { + split := strings.SplitN(f, "=", 2) + if len(split) < 2 { + return fmt.Errorf("invalid filter %q", f) + } + stopOptions.Filters[split[0]] = append(stopOptions.Filters[split[0]], split[1]) + } + responses, err := registry.ContainerEngine().ContainerStop(context.Background(), args, stopOptions) if err != nil { return err diff --git a/cmd/podman/validate/args.go b/cmd/podman/validate/args.go index 39eedca64..6d212665d 100644 --- a/cmd/podman/validate/args.go +++ b/cmd/podman/validate/args.go @@ -86,6 +86,13 @@ func CheckAllLatestAndIDFile(c *cobra.Command, args []string, ignoreArgLen bool, specifiedIDFile = true } + if c.Flags().Changed("filter") { + if argLen > 0 { + return errors.New("--filter takes no arguments") + } + return nil + } + if specifiedIDFile && (specifiedAll || specifiedLatest) { return fmt.Errorf("--all, --latest, and --%s cannot be used together", idFileFlag) } else if specifiedAll && specifiedLatest { diff --git a/docs/source/markdown/podman-stop.1.md b/docs/source/markdown/podman-stop.1.md index e35ab9182..cfc49afa1 100644 --- a/docs/source/markdown/podman-stop.1.md +++ b/docs/source/markdown/podman-stop.1.md @@ -25,6 +25,30 @@ Stop all running containers. This does not include paused containers. 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 diff --git a/pkg/api/handlers/compat/containers_stop.go b/pkg/api/handlers/compat/containers_stop.go index 33bb3a679..c9a27dd83 100644 --- a/pkg/api/handlers/compat/containers_stop.go +++ b/pkg/api/handlers/compat/containers_stop.go @@ -33,9 +33,7 @@ func StopContainer(w http.ResponseWriter, r *http.Request) { utils.Error(w, http.StatusBadRequest, fmt.Errorf("failed to parse parameters for %s: %w", r.URL.String(), err)) return } - name := utils.GetName(r) - options := entities.StopOptions{ Ignore: query.Ignore, } diff --git a/pkg/domain/entities/containers.go b/pkg/domain/entities/containers.go index 17408f12f..934a7cbdc 100644 --- a/pkg/domain/entities/containers.go +++ b/pkg/domain/entities/containers.go @@ -80,6 +80,7 @@ type PauseUnpauseReport struct { } type StopOptions struct { + Filters map[string][]string All bool Ignore bool Latest bool diff --git a/pkg/domain/infra/abi/containers.go b/pkg/domain/infra/abi/containers.go index 23a591604..04eb85504 100644 --- a/pkg/domain/infra/abi/containers.go +++ b/pkg/domain/infra/abi/containers.go @@ -37,12 +37,29 @@ import ( ) // getContainersAndInputByContext gets containers whether all, latest, or a slice of names/ids -// is specified. It also returns a list of the corresponding input name used to look up each container. -func getContainersAndInputByContext(all, latest bool, names []string, runtime *libpod.Runtime) (ctrs []*libpod.Container, rawInput []string, err error) { +// is specified. It also returns a list of the corresponding input name used to lookup each container. +func getContainersAndInputByContext(all, latest bool, names []string, filters map[string][]string, runtime *libpod.Runtime) (ctrs []*libpod.Container, rawInput []string, err error) { var ctr *libpod.Container ctrs = []*libpod.Container{} + filterFuncs := make([]libpod.ContainerFilter, 0, len(filters)) switch { + case len(filters) > 0: + for k, v := range filters { + generatedFunc, err := dfilters.GenerateContainerFilterFuncs(k, v, runtime) + if err != nil { + return nil, nil, err + } + filterFuncs = append(filterFuncs, generatedFunc) + } + ctrs, err = runtime.GetContainers(filterFuncs...) + if err != nil { + return nil, nil, err + } + rawInput = []string{} + for _, candidate := range ctrs { + rawInput = append(rawInput, candidate.ID()) + } case all: ctrs, err = runtime.GetAllContainers() case latest: @@ -66,13 +83,13 @@ func getContainersAndInputByContext(all, latest bool, names []string, runtime *l } } } - return + return ctrs, rawInput, err } // getContainersByContext gets containers whether all, latest, or a slice of names/ids // is specified. func getContainersByContext(all, latest bool, names []string, runtime *libpod.Runtime) (ctrs []*libpod.Container, err error) { - ctrs, _, err = getContainersAndInputByContext(all, latest, names, runtime) + ctrs, _, err = getContainersAndInputByContext(all, latest, names, nil, runtime) return } @@ -150,7 +167,7 @@ func (ic *ContainerEngine) ContainerUnpause(ctx context.Context, namesOrIds []st } func (ic *ContainerEngine) ContainerStop(ctx context.Context, namesOrIds []string, options entities.StopOptions) ([]*entities.StopReport, error) { names := namesOrIds - ctrs, rawInputs, err := getContainersAndInputByContext(options.All, options.Latest, names, ic.Libpod) + ctrs, rawInputs, err := getContainersAndInputByContext(options.All, options.Latest, names, options.Filters, ic.Libpod) if err != nil && !(options.Ignore && errors.Is(err, define.ErrNoSuchCtr)) { return nil, err } @@ -228,7 +245,7 @@ func (ic *ContainerEngine) ContainerKill(ctx context.Context, namesOrIds []strin if err != nil { return nil, err } - ctrs, rawInputs, err := getContainersAndInputByContext(options.All, options.Latest, namesOrIds, ic.Libpod) + ctrs, rawInputs, err := getContainersAndInputByContext(options.All, options.Latest, namesOrIds, nil, ic.Libpod) if err != nil { return nil, err } @@ -874,7 +891,7 @@ func (ic *ContainerEngine) ContainerStart(ctx context.Context, namesOrIds []stri } } } - ctrs, rawInputs, err := getContainersAndInputByContext(all, options.Latest, containersNamesOrIds, ic.Libpod) + ctrs, rawInputs, err := getContainersAndInputByContext(all, options.Latest, containersNamesOrIds, options.Filters, ic.Libpod) if err != nil { return nil, err } diff --git a/pkg/domain/infra/tunnel/containers.go b/pkg/domain/infra/tunnel/containers.go index 5568ccde8..fcabff7c4 100644 --- a/pkg/domain/infra/tunnel/containers.go +++ b/pkg/domain/infra/tunnel/containers.go @@ -91,8 +91,7 @@ func (ic *ContainerEngine) ContainerUnpause(ctx context.Context, namesOrIds []st } func (ic *ContainerEngine) ContainerStop(ctx context.Context, namesOrIds []string, opts entities.StopOptions) ([]*entities.StopReport, error) { - reports := []*entities.StopReport{} - ctrs, rawInputs, err := getContainersAndInputByContext(ic.ClientCtx, opts.All, opts.Ignore, namesOrIds) + ctrs, rawInputs, err := getContainersAndInputByContext(ic.ClientCtx, opts.All, opts.Ignore, namesOrIds, opts.Filters) if err != nil { return nil, err } @@ -104,6 +103,7 @@ func (ic *ContainerEngine) ContainerStop(ctx context.Context, namesOrIds []strin if to := opts.Timeout; to != nil { options.WithTimeout(*to) } + reports := []*entities.StopReport{} for _, c := range ctrs { report := entities.StopReport{ Id: c.ID, @@ -134,7 +134,7 @@ func (ic *ContainerEngine) ContainerStop(ctx context.Context, namesOrIds []strin } func (ic *ContainerEngine) ContainerKill(ctx context.Context, namesOrIds []string, opts entities.KillOptions) ([]*entities.KillReport, error) { - ctrs, rawInputs, err := getContainersAndInputByContext(ic.ClientCtx, opts.All, false, namesOrIds) + ctrs, rawInputs, err := getContainersAndInputByContext(ic.ClientCtx, opts.All, false, namesOrIds, nil) if err != nil { return nil, err } diff --git a/pkg/domain/infra/tunnel/helpers.go b/pkg/domain/infra/tunnel/helpers.go index 24b2b619d..9ff1641f0 100644 --- a/pkg/domain/infra/tunnel/helpers.go +++ b/pkg/domain/infra/tunnel/helpers.go @@ -15,25 +15,29 @@ import ( // FIXME: the `ignore` parameter is very likely wrong here as it should rather // be used on *errors* from operations such as remove. func getContainersByContext(contextWithConnection context.Context, all, ignore bool, namesOrIDs []string) ([]entities.ListContainer, error) { - ctrs, _, err := getContainersAndInputByContext(contextWithConnection, all, ignore, namesOrIDs) + ctrs, _, err := getContainersAndInputByContext(contextWithConnection, all, ignore, namesOrIDs, nil) return ctrs, err } -func getContainersAndInputByContext(contextWithConnection context.Context, all, ignore bool, namesOrIDs []string) ([]entities.ListContainer, []string, error) { +func getContainersAndInputByContext(contextWithConnection context.Context, all, ignore bool, namesOrIDs []string, filters map[string][]string) ([]entities.ListContainer, []string, error) { if all && len(namesOrIDs) > 0 { return nil, nil, errors.New("cannot look up containers and all") } - options := new(containers.ListOptions).WithAll(true).WithSync(true) + options := new(containers.ListOptions).WithAll(true).WithSync(true).WithFilters(filters) allContainers, err := containers.List(contextWithConnection, options) if err != nil { return nil, nil, err } rawInputs := []string{} - if all { + switch { + case len(filters) > 0: + for i := range allContainers { + namesOrIDs = append(namesOrIDs, allContainers[i].ID) + } + case all: for i := range allContainers { rawInputs = append(rawInputs, allContainers[i].ID) } - return allContainers, rawInputs, err } diff --git a/test/e2e/stop_test.go b/test/e2e/stop_test.go index 97d8ba701..7a258466a 100644 --- a/test/e2e/stop_test.go +++ b/test/e2e/stop_test.go @@ -1,6 +1,7 @@ package integration import ( + "fmt" "io/ioutil" "os" "strings" @@ -363,4 +364,45 @@ var _ = Describe("Podman stop", func() { Expect(session).Should(Exit(0)) Expect(podmanTest.NumberOfContainersRunning()).To(Equal(0)) }) + + It("podman stop --filter", func() { + session1 := podmanTest.Podman([]string{"container", "create", ALPINE}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + cid1 := session1.OutputToString() + + session1 = podmanTest.Podman([]string{"container", "create", ALPINE}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + cid2 := session1.OutputToString() + + session1 = podmanTest.Podman([]string{"container", "create", ALPINE}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + cid3 := session1.OutputToString() + shortCid3 := cid3[0:5] + + session1 = podmanTest.Podman([]string{"start", "--all"}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + + session1 = podmanTest.Podman([]string{"stop", cid1, "-f", "status=running"}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(125)) + + session1 = podmanTest.Podman([]string{"stop", "-a", "--filter", fmt.Sprintf("id=%swrongid", shortCid3)}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + Expect(session1.OutputToString()).To(HaveLen(0)) + + session1 = podmanTest.Podman([]string{"stop", "-a", "--filter", fmt.Sprintf("id=%s", shortCid3)}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + Expect(session1.OutputToString()).To(BeEquivalentTo(cid3)) + + session1 = podmanTest.Podman([]string{"stop", "-f", fmt.Sprintf("id=%s", cid2)}) + session1.WaitWithDefaultTimeout() + Expect(session1).Should(Exit(0)) + Expect(session1.OutputToString()).To(BeEquivalentTo(cid2)) + }) }) -- cgit v1.2.3-54-g00ecf From 53edd9b654d558ff769286ef948ab0f6a23c68cc Mon Sep 17 00:00:00 2001 From: Jake Correnti Date: Wed, 13 Jul 2022 21:41:16 -0400 Subject: Podman pull --all-tags shorthand option I added the shorthand option for `podman pull --all-tags`. Like Docker, Podman can now do `podman pull -a`. Signed-off-by: Jake Correnti --- cmd/podman/images/pull.go | 2 +- docs/source/markdown/podman-pull.1.md | 2 +- test/e2e/pull_test.go | 9 +++++++++ 3 files changed, 11 insertions(+), 2 deletions(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/images/pull.go b/cmd/podman/images/pull.go index 6e3ec1517..8211ceba5 100644 --- a/cmd/podman/images/pull.go +++ b/cmd/podman/images/pull.go @@ -77,7 +77,7 @@ func init() { func pullFlags(cmd *cobra.Command) { flags := cmd.Flags() - flags.BoolVar(&pullOptions.AllTags, "all-tags", false, "All tagged images in the repository will be pulled") + flags.BoolVarP(&pullOptions.AllTags, "all-tags", "a", false, "All tagged images in the repository will be pulled") credsFlagName := "creds" flags.StringVar(&pullOptions.CredentialsCLI, credsFlagName, "", "`Credentials` (USERNAME:PASSWORD) to use for authenticating to a registry") diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 928bbc6fe..99e227226 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -43,7 +43,7 @@ $ podman pull oci-archive:/tmp/myimage ``` ## OPTIONS -#### **--all-tags** +#### **--all-tags**, **-a** All tagged images in the repository will be pulled. diff --git a/test/e2e/pull_test.go b/test/e2e/pull_test.go index 04b7a280d..12f14fdc8 100644 --- a/test/e2e/pull_test.go +++ b/test/e2e/pull_test.go @@ -108,6 +108,15 @@ var _ = Describe("Podman pull", func() { session.WaitWithDefaultTimeout() Expect(session).Should(Exit(0)) Expect(len(session.OutputToStringArray())).To(BeNumerically(">=", 2), "Expected at least two images") + + session = podmanTest.Podman([]string{"pull", "-a", "quay.io/libpod/testdigest_v2s2"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + + session = podmanTest.Podman([]string{"images"}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + Expect(len(session.OutputToStringArray())).To(BeNumerically(">=", 2), "Expected at least two images") }) It("podman pull from docker with nonexistent --authfile", func() { -- cgit v1.2.3-54-g00ecf From 24405503056adfdd5393b7f86e5faf5885cd404c Mon Sep 17 00:00:00 2001 From: Toshiki Sonoda Date: Tue, 19 Jul 2022 17:22:52 +0900 Subject: [CI:DOCS] Fix typo in manifest manpage rme -> rm Signed-off-by: Toshiki Sonoda --- docs/source/markdown/podman-manifest.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-manifest.1.md b/docs/source/markdown/podman-manifest.1.md index 5ff44c1d5..cc716b2a0 100644 --- a/docs/source/markdown/podman-manifest.1.md +++ b/docs/source/markdown/podman-manifest.1.md @@ -22,7 +22,7 @@ The `podman manifest` command provides subcommands which can be used to: | inspect | [podman-manifest-inspect(1)](podman-manifest-inspect.1.md) | Display a manifest list or image index. | | push | [podman-manifest-push(1)](podman-manifest-push.1.md) | Push a manifest list or image index to a registry. | | remove | [podman-manifest-remove(1)](podman-manifest-remove.1.md) | Remove an image from a manifest list or image index. | -| rm | [podman-manifest-rme(1)](podman-manifest-rm.1.md) | Remove manifest list or image index from local storage. | +| rm | [podman-manifest-rm(1)](podman-manifest-rm.1.md) | Remove manifest list or image index from local storage. | ## EXAMPLES -- cgit v1.2.3-54-g00ecf From c3c07ed09eb9e5998f2c67f1054850a5b8266aae Mon Sep 17 00:00:00 2001 From: Urvashi Mohnani Date: Tue, 19 Jul 2022 11:58:27 -0400 Subject: Update init ctr default for play kube Update the init container type default to once instead of always to match k8s behavior. Add a new annotation that can be used to change the init ctr type in the kube yaml. Signed-off-by: Urvashi Mohnani --- docs/source/markdown/podman-play-kube.1.md | 2 +- libpod/define/annotations.go | 5 +++++ pkg/domain/infra/abi/play.go | 6 +++++- test/e2e/play_kube_test.go | 29 +++++++++++++++++++++++++++-- 4 files changed, 38 insertions(+), 4 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 47e438bd6..66341d875 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -22,7 +22,7 @@ Currently, the supported Kubernetes kinds are: Only two volume types are supported by play kube, the *hostPath* and *persistentVolumeClaim* volume types. For the *hostPath* volume type, only the *default (empty)*, *DirectoryOrCreate*, *Directory*, *FileOrCreate*, *File*, *Socket*, *CharDevice* and *BlockDevice* subtypes are supported. Podman interprets the value of *hostPath* *path* as a file path when it contains at least one forward slash, otherwise Podman treats the value as the name of a named volume. When using a *persistentVolumeClaim*, the value for *claimName* is the name for the Podman named volume. -Note: When playing a kube YAML with init containers, the init container will be created with init type value `always`. +Note: When playing a kube YAML with init containers, the init container will be created with init type value `once`. To change the default type, use the `io.podman.annotations.init.container.type` annotation to set the type to `always`. Note: *hostPath* volume types created by play kube will be given an SELinux shared label (z), bind mounts are not relabeled (use `chcon -t container_file_t -R `). diff --git a/libpod/define/annotations.go b/libpod/define/annotations.go index 8f5279981..580286d6a 100644 --- a/libpod/define/annotations.go +++ b/libpod/define/annotations.go @@ -135,6 +135,11 @@ const ( // creating a checkpoint image to specify the name of host distribution on // which the checkpoint was created. CheckpointAnnotationDistributionName = "io.podman.annotations.checkpoint.distribution.name" + + // InitContainerType is used by play kube when playing a kube yaml to specify the type + // of the init container. + InitContainerType = "io.podman.annotations.init.container.type" + // MaxKubeAnnotation is the max length of annotations allowed by Kubernetes. MaxKubeAnnotation = 63 ) diff --git a/pkg/domain/infra/abi/play.go b/pkg/domain/infra/abi/play.go index c913fdb69..8b47eff53 100644 --- a/pkg/domain/infra/abi/play.go +++ b/pkg/domain/infra/abi/play.go @@ -507,13 +507,17 @@ func (ic *ContainerEngine) playKubePod(ctx context.Context, podName string, podY for k, v := range podSpec.PodSpecGen.Labels { // add podYAML labels labels[k] = v } + initCtrType := annotations[define.InitContainerType] + if initCtrType == "" { + initCtrType = define.OneShotInitContainer + } specgenOpts := kube.CtrSpecGenOptions{ Annotations: annotations, ConfigMaps: configMaps, Container: initCtr, Image: pulledImage, - InitContainerType: define.AlwaysInitContainer, + InitContainerType: initCtrType, Labels: labels, LogDriver: options.LogDriver, LogOptions: options.LogOptions, diff --git a/test/e2e/play_kube_test.go b/test/e2e/play_kube_test.go index 457aaebb2..9e2d4de19 100644 --- a/test/e2e/play_kube_test.go +++ b/test/e2e/play_kube_test.go @@ -1559,8 +1559,10 @@ var _ = Describe("Podman play kube", func() { }) // If you have an init container in the pod yaml, podman should create and run the init container with play kube - It("podman play kube test with init containers", func() { - pod := getPod(withPodInitCtr(getCtr(withImage(ALPINE), withCmd([]string{"echo", "hello"}), withInitCtr(), withName("init-test"))), withCtr(getCtr(withImage(ALPINE), withCmd([]string{"top"})))) + // With annotation set to always + It("podman play kube test with init containers and annotation set", func() { + // With the init container type annotation set to always + pod := getPod(withAnnotation("io.podman.annotations.init.container.type", "always"), withPodInitCtr(getCtr(withImage(ALPINE), withCmd([]string{"echo", "hello"}), withInitCtr(), withName("init-test"))), withCtr(getCtr(withImage(ALPINE), withCmd([]string{"top"})))) err := generateKubeYaml("pod", pod, kubeYaml) Expect(err).To(BeNil()) @@ -1585,6 +1587,29 @@ var _ = Describe("Podman play kube", func() { Expect(inspect.OutputToString()).To(ContainSubstring("running")) }) + // If you have an init container in the pod yaml, podman should create and run the init container with play kube + // Using default init container type (once) + It("podman play kube test with init container type set to default value", func() { + // Using the default init container type (once) + pod := getPod(withPodInitCtr(getCtr(withImage(ALPINE), withCmd([]string{"echo", "hello"}), withInitCtr(), withName("init-test"))), withCtr(getCtr(withImage(ALPINE), withCmd([]string{"top"})))) + err := generateKubeYaml("pod", pod, kubeYaml) + Expect(err).To(BeNil()) + + kube := podmanTest.Podman([]string{"play", "kube", kubeYaml}) + kube.WaitWithDefaultTimeout() + Expect(kube).Should(Exit(0)) + + // Expect the number of containers created to be 2, infra and regular container + numOfCtrs := podmanTest.NumberOfContainers() + Expect(numOfCtrs).To(Equal(2)) + + // Regular container should be in running state + inspect := podmanTest.Podman([]string{"inspect", "--format", "{{.State.Status}}", "testPod-" + defaultCtrName}) + inspect.WaitWithDefaultTimeout() + Expect(inspect).Should(Exit(0)) + Expect(inspect.OutputToString()).To(ContainSubstring("running")) + }) + // If you supply only args for a Container, the default Entrypoint defined in the Docker image is run with the args that you supplied. It("podman play kube test correct command with only set args in yaml file", func() { pod := getPod(withCtr(getCtr(withImage(REGISTRY_IMAGE), withCmd(nil), withArg([]string{"echo", "hello"})))) -- cgit v1.2.3-54-g00ecf From 86159e39bcaeaa83a1861405f6062896f83af436 Mon Sep 17 00:00:00 2001 From: Charlie Doern Date: Mon, 18 Jul 2022 10:02:33 -0400 Subject: document isolate option for network create [CI:DOCS] document the podman network create -o=isolate which allows networks to cut themselves off from external connections. resolves #5805 Signed-off-by: Charlie Doern --- docs/source/markdown/podman-network-create.1.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 3587ac2a8..0ccc540f8 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -73,8 +73,9 @@ Set driver specific options. All drivers accept the `mtu` option. The `mtu` option sets the Maximum Transmission Unit (MTU) and takes an integer value. -Additionally the `bridge` driver supports the following option: +Additionally the `bridge` driver supports the following options: - `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. +- `isolate`: This option isolates networks by blocking traffic between those that have this option enabled. The `macvlan` and `ipvlan` driver support the following options: - `parent`: The host device which should be used for the macvlan interface. Defaults to the default route interface. -- cgit v1.2.3-54-g00ecf From 206f11d4fbda23c2dbae8c15014f01809b9bdd68 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 18 Jul 2022 07:53:39 -0600 Subject: Makefile: use order-only prereq for podman-remote podman-remote has a dependency on $(SRCBINDIR), because on Mac and Windows that's a special dir that may not exist. But depending on a directory means depending on its mtime, which changes every time a file in it is updated, which means running 'make' twice in a row will rebuild podman-remote for no good reason. Solution: GNU Make has the concept of "order-only" prerequisites, precisely for this situation. Use it. Since it's an obscure feature, document it. UPDATE: This exposed some nasty duplication wrt podman-remote rules. Clean those up, and add comments to some confusing sections. Fixes: #14756 (Also, drive-by edit to remove a stray misdocumented non-option) Signed-off-by: Ed Santiago --- Makefile | 47 +++++++++++---------------------- docs/remote-docs.sh | 4 ++- docs/source/markdown/podman-import.1.md | 4 --- 3 files changed, 18 insertions(+), 37 deletions(-) (limited to 'docs/source/markdown') diff --git a/Makefile b/Makefile index 27a961574..90c3d98a1 100644 --- a/Makefile +++ b/Makefile @@ -146,7 +146,8 @@ CROSS_BUILD_TARGETS := \ # Dereference variable $(1), return value if non-empty, otherwise raise an error. err_if_empty = $(if $(strip $($(1))),$(strip $($(1))),$(error Required variable $(1) value is undefined, whitespace, or empty)) -# Podman does not work w/o CGO_ENABLED, except in some very specific cases +# Podman does not work w/o CGO_ENABLED, except in some very specific cases. +# Windows and Mac (both podman-remote client only) require CGO_ENABLED=0. CGO_ENABLED ?= 1 # Default to the native OS type and architecture unless otherwise specified NATIVE_GOOS := $(shell env -u GOOS $(GO) env GOOS) @@ -157,9 +158,11 @@ GOARCH ?= $(NATIVE_GOARCH) ifeq ($(call err_if_empty,GOOS),windows) BINSFX := .exe SRCBINDIR := bin/windows +CGO_ENABLED := 0 else ifeq ($(GOOS),darwin) BINSFX := SRCBINDIR := bin/darwin +CGO_ENABLED := 0 else BINSFX := -remote SRCBINDIR := bin @@ -302,7 +305,8 @@ endif $(SRCBINDIR): mkdir -p $(SRCBINDIR) -$(SRCBINDIR)/podman$(BINSFX): $(SRCBINDIR) $(SOURCES) go.mod go.sum +# '|' is to ignore SRCBINDIR mtime; see: info make 'Types of Prerequisites' +$(SRCBINDIR)/podman$(BINSFX): $(SOURCES) go.mod go.sum | $(SRCBINDIR) $(GOCMD) build \ $(BUILDFLAGS) \ $(GO_LDFLAGS) '$(LDFLAGS_PODMAN)' \ @@ -322,28 +326,13 @@ $(SRCBINDIR)/podman-remote-static: $(SRCBINDIR) $(SOURCES) go.mod go.sum .PHONY: podman podman: bin/podman +# This will map to the right thing on Linux, Windows, and Mac. .PHONY: podman-remote -podman-remote: $(SRCBINDIR) $(SRCBINDIR)/podman$(BINSFX) ## Build podman-remote binary - -# A wildcard podman-remote-% target incorrectly sets GOOS for release targets -.PHONY: podman-remote-linux -podman-remote-linux: ## Build podman-remote for Linux - $(MAKE) \ - CGO_ENABLED=0 \ - GOOS=linux \ - GOARCH=$(GOARCH) \ - bin/podman-remote +podman-remote: $(SRCBINDIR)/podman$(BINSFX) PHONY: podman-remote-static podman-remote-static: $(SRCBINDIR)/podman-remote-static -.PHONY: podman-remote-windows -podman-remote-windows: ## Build podman-remote for Windows - $(MAKE) \ - CGO_ENABLED=0 \ - GOOS=windows \ - bin/windows/podman.exe - .PHONY: podman-winpath podman-winpath: $(SOURCES) go.mod go.sum CGO_ENABLED=0 \ @@ -354,14 +343,6 @@ podman-winpath: $(SOURCES) go.mod go.sum -o bin/windows/winpath.exe \ ./cmd/winpath -.PHONY: podman-remote-darwin -podman-remote-darwin: podman-mac-helper ## Build podman-remote for macOS - $(MAKE) \ - CGO_ENABLED=$(DARWIN_GCO) \ - GOOS=darwin \ - GOARCH=$(GOARCH) \ - bin/darwin/podman - .PHONY: podman-mac-helper podman-mac-helper: ## Build podman-mac-helper for macOS CGO_ENABLED=0 \ @@ -456,8 +437,10 @@ docdir: docs: $(MANPAGES) ## Generate documentation # docs/remote-docs.sh requires a locally executable 'podman-remote' binary -# in addition to the target-archetecture binary (if any). -podman-remote-%-docs: podman-remote-$(call err_if_empty,NATIVE_GOOS) +# in addition to the target-architecture binary (if different). That's +# what the NATIVE_GOOS make does in the first line. +podman-remote-%-docs: podman-remote + $(MAKE) podman-remote GOOS=$(NATIVE_GOOS) $(eval GOOS := $*) $(MAKE) docs $(MANPAGES) rm -rf docs/build/remote @@ -685,9 +668,9 @@ podman-remote-release-%.zip: test/version/version ## Build podman-remote for %=$ clean-binaries podman-remote-$(GOOS)-docs if [[ "$(GOARCH)" != "$(NATIVE_GOARCH)" ]]; then \ $(MAKE) CGO_ENABLED=0 $(GOPLAT) BUILDTAGS="$(BUILDTAGS_CROSS)" \ - clean-binaries podman-remote-$(GOOS); \ + clean-binaries podman-remote; \ else \ - $(MAKE) $(GOPLAT) podman-remote-$(GOOS); \ + $(MAKE) $(GOPLAT) podman-remote; \ fi cp -r ./docs/build/remote/$(GOOS) "$(TMPDIR)/$(SUBDIR)/docs/" cp ./contrib/remote/containers.conf "$(TMPDIR)/$(SUBDIR)/" @@ -700,7 +683,7 @@ podman-remote-release-%.zip: test/version/version ## Build podman-remote for %=$ .PHONY: podman.msi podman.msi: test/version/version ## Build podman-remote, package for installation on Windows $(MAKE) podman-v$(call err_if_empty,RELEASE_NUMBER).msi -podman-v%.msi: test/version/version podman-remote-windows podman-remote-windows-docs podman-winpath win-sshproxy +podman-v%.msi: test/version/version podman-remote podman-remote-windows-docs podman-winpath win-sshproxy $(eval DOCFILE := docs/build/remote/windows) find $(DOCFILE) -print | \ wixl-heat --var var.ManSourceDir --component-group ManFiles \ diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh index 4c2602f80..f281c19ff 100755 --- a/docs/remote-docs.sh +++ b/docs/remote-docs.sh @@ -6,7 +6,9 @@ PLATFORM=$1 ## linux, windows or darwin TARGET=${2} ## where to output files SOURCES=${@:3} ## directories to find markdown files -# Overridden for testing. Native podman-remote binary expected filepaths +# This is a *native* binary, one we can run on this host. (This script can be +# invoked in a cross-compilation environment, so even if PLATFORM=windows +# we need an actual executable that we can invoke). if [[ -z "$PODMAN" ]]; then case $(env -i HOME=$HOME PATH=$PATH go env GOOS) in windows) diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index 4002f5255..8d482b961 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -50,10 +50,6 @@ Shows progress on the import Set variant of the imported image. -**--verbose** - -Print additional debugging information - ## EXAMPLES ``` -- cgit v1.2.3-54-g00ecf From c7fef73166d4a5b91bdcfe34285b81e1a625be61 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Fri, 22 Jul 2022 13:46:28 +0200 Subject: docs: remove CNI word where it is not applicable Most network commands/features work with both netavark and CNI. When we added added netavark most docs were not vetted and thus still use CNI network, it should just say network. Fixes #14990 Signed-off-by: Paul Holzinger --- cmd/podman/networks/create.go | 2 +- cmd/podman/networks/inspect.go | 4 ++-- commands-demo.md | 14 +++++++------- docs/source/markdown/podman-create.1.md | 9 ++++++--- docs/source/markdown/podman-network-connect.1.md | 10 +++++----- docs/source/markdown/podman-network-create.1.md | 12 +++++------- docs/source/markdown/podman-network-inspect.1.md | 6 +++--- docs/source/markdown/podman-network-ls.1.md | 6 +++--- docs/source/markdown/podman-network-rm.1.md | 6 +++--- docs/source/markdown/podman-network.1.md | 2 +- docs/source/markdown/podman-play-kube.1.md | 2 +- docs/source/markdown/podman-pod-create.1.md | 9 ++++++--- docs/source/markdown/podman-run.1.md | 9 ++++++--- docs/tutorials/basic_networking.md | 6 +++--- 14 files changed, 52 insertions(+), 45 deletions(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/networks/create.go b/cmd/podman/networks/create.go index 2cf7023f3..8b0ebeb2b 100644 --- a/cmd/podman/networks/create.go +++ b/cmd/podman/networks/create.go @@ -17,7 +17,7 @@ import ( ) var ( - networkCreateDescription = `create CNI networks for containers and pods` + networkCreateDescription = `create networks for containers and pods` networkCreateCommand = &cobra.Command{ Use: "create [options] [NAME]", Short: "network create", diff --git a/cmd/podman/networks/inspect.go b/cmd/podman/networks/inspect.go index 1a8444147..14f62cbd1 100644 --- a/cmd/podman/networks/inspect.go +++ b/cmd/podman/networks/inspect.go @@ -13,8 +13,8 @@ var ( networkinspectDescription = `Inspect network` networkinspectCommand = &cobra.Command{ Use: "inspect [options] NETWORK [NETWORK...]", - Short: "Displays the raw CNI network configuration for one or more networks.", - Long: networkinspectDescription, + Long: "Displays the network configuration for one or more networks.", + Short: networkinspectDescription, RunE: networkInspect, Example: `podman network inspect podman`, Args: cobra.MinimumNArgs(1), diff --git a/commands-demo.md b/commands-demo.md index c1413dd9e..dac279192 100644 --- a/commands-demo.md +++ b/commands-demo.md @@ -45,13 +45,13 @@ | [podman-logout(1)](https://podman.readthedocs.io/en/latest/markdown/podman-logout.1.html) | Logout of a container registry | | [podman-logs(1)](https://podman.readthedocs.io/en/latest/markdown/podman-logs.1.html) | Display the logs of one or more containers | | [podman-mount(1)](https://podman.readthedocs.io/en/latest/markdown/podman-mount.1.html) | Mount a working container's root filesystem | -| [podman-network(1)](https://podman.readthedocs.io/en/latest/network.html) | Manage Podman CNI networks | -| [podman-network-create(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-create.1.html) | Create a CNI network | -| [podman-network-connect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-connect.1.html) | Connect a container to a CNI network | -| [podman-network-disconnect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-disconnect.1.html) | Disconnect a container from a CNI network | -| [podman-network-inspect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-inspect.1.html) | Displays the raw CNI network configuration for one or more networks | -| [podman-network-ls(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-ls.1.html) | Display a summary of CNI networks | -| [podman-network-rm(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-rm.1.html) | Remove one or more CNI networks | +| [podman-network(1)](https://podman.readthedocs.io/en/latest/network.html) | Manage Podman networks | +| [podman-network-create(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-create.1.html) | Create a network | +| [podman-network-connect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-connect.1.html) | Connect a container to a network | +| [podman-network-disconnect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-disconnect.1.html) | Disconnect a container from a network | +| [podman-network-inspect(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-inspect.1.html) | Displays the network configuration for one or more networks | +| [podman-network-ls(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-ls.1.html) | Display a summary of networks | +| [podman-network-rm(1)](https://podman.readthedocs.io/en/latest/markdown/podman-network-rm.1.html) | Remove one or more networks | | [podman-pause(1)](https://podman.readthedocs.io/en/latest/markdown/podman-pause.1.html) | Pause one or more running containers | [![...](/docs/source/markdown/play.png)](https://podman.io/asciinema/podman/pause_unpause/) | [Here](https://github.com/containers/Demos/blob/master/podman_cli/podman_pause_unpause.sh) | | [podman-play(1)](https://podman.readthedocs.io/en/latest/play.html) | Play a pod | | [podman-play-kube(1)](https://podman.readthedocs.io/en/latest/markdown/podman-play-kube.1.html) | Create pods and containers based on Kubernetes YAML | diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 67bb573e2..6a951b421 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -738,9 +738,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} `), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-healthcheck** diff --git a/docs/source/markdown/podman-network-connect.1.md b/docs/source/markdown/podman-network-connect.1.md index c3eef4038..d1718b812 100644 --- a/docs/source/markdown/podman-network-connect.1.md +++ b/docs/source/markdown/podman-network-connect.1.md @@ -12,10 +12,10 @@ Once connected, the container can communicate with other containers in the same ## OPTIONS #### **--alias**=*name* -Add network-scoped alias for the container. If the network is using the `dnsname` CNI plugin, these aliases -can be used for name resolution on the given network. Multiple *--alias* options may be specified as input. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation -that will be removed in a later release. +Add network-scoped alias for the container. If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} `), +these aliases can be used for name resolution on the given network. Multiple *--alias* options may be specified as input. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--ip**=*address* Set a static ipv4 address for this container on this network. @@ -44,7 +44,7 @@ podman network connect --ip 10.89.1.13 test web ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-disconnect(1)](podman-network-disconnect.1.md)** +**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-disconnect(1)](podman-network-disconnect.1.md)** ## HISTORY November 2020, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 0ccc540f8..3836ea05c 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -7,11 +7,9 @@ podman\-network-create - Create a Podman network **podman network create** [*options*] [*name*] ## DESCRIPTION -Create a CNI-network configuration for use with Podman. By default, Podman creates a bridge connection. +Create a network configuration for use with Podman. By default, Podman creates a bridge connection. A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan can -be designated with the *-o parent=``* option. In the case of *Macvlan* connections, the -CNI *dhcp* plugin needs to be activated or the container image must have a DHCP client to interact -with the host network's DHCP server. +be designated with the *-o parent=``* option. If no options are provided, Podman will assign a free subnet and name for your network. @@ -54,7 +52,7 @@ The argument order of the **--subnet**, **--gateway** and **--ip-range** options Set the ipam driver (IP Address Management Driver) for the network. When unset podman will choose an ipam driver automatically based on the network driver. Valid values are: - `host-local`: IP addresses are assigned locally. - - `dhcp`: IP addresses are assigned from a dhcp server on your network. This driver is not yet supported with netavark. + - `dhcp`: IP addresses are assigned from a dhcp server on your network. This driver is not yet supported with netavark. For CNI the *dhcp* plugin needs to be activated before. - `none`: No ip addresses are assigned to the interfaces. You can see the driver in the **podman network inspect** output under the `ipam_options` field. @@ -94,7 +92,7 @@ This is useful to set a static ipv4 and ipv6 subnet. Create a network with no options. ``` $ podman network create -cni-podman2 +podman2 ``` Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. @@ -118,7 +116,7 @@ newnet Create a network that uses a *192.168.55.0/24** subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. ``` $ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 -cni-podman5 +podman5 ``` Create a network with a static ipv4 and ipv6 subnet and set a gateway. diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index ba9cc94d5..2ba4a63cb 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -1,13 +1,13 @@ % podman-network-inspect(1) ## NAME -podman\-network\-inspect - Displays the raw network configuration for one or more networks +podman\-network\-inspect - Displays the network configuration for one or more networks ## SYNOPSIS **podman network inspect** [*options*] *network* [*network* ...] ## DESCRIPTION -Display the raw (JSON format) network configuration. +Display the (JSON format) network configuration. ## OPTIONS #### **--format**, **-f**=*format* @@ -40,7 +40,7 @@ $ podman network inspect podman "name": "podman", "id": "2f259bab93aaaaa2542ba43ef33eb990d0999ee1b9924b557b7be53c0b7a1bb9", "driver": "bridge", - "network_interface": "cni-podman0", + "network_interface": "podman0", "created": "2021-06-03T12:04:33.088567413+02:00", "subnets": [ { diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md index 3c696d404..c7ea24b9b 100644 --- a/docs/source/markdown/podman-network-ls.1.md +++ b/docs/source/markdown/podman-network-ls.1.md @@ -77,8 +77,8 @@ Display networks $ podman network ls NETWORK ID NAME DRIVER 88a7120ee19d podman bridge -6dd508dbf8cd cni-podman6 bridge -8e35c2cd3bf6 cni-podman5 macvlan +6dd508dbf8cd podman6 bridge +8e35c2cd3bf6 podman5 macvlan ``` Display only network names @@ -101,7 +101,7 @@ List networks with their subnets ``` $ podman network ls --format "{{.Name}}: {{range .Subnets}}{{.Subnet}} {{end}}" podman: 10.88.0.0/16 -cni-podman3: 10.89.30.0/24 fde4:f86f:4aab:e68f::/64 +podman3: 10.89.30.0/24 fde4:f86f:4aab:e68f::/64 macvlan: ``` diff --git a/docs/source/markdown/podman-network-rm.1.md b/docs/source/markdown/podman-network-rm.1.md index c6e33c571..880f1d0c7 100644 --- a/docs/source/markdown/podman-network-rm.1.md +++ b/docs/source/markdown/podman-network-rm.1.md @@ -21,11 +21,11 @@ Seconds to wait before forcibly stopping the running containers that are using t ## EXAMPLE -Delete the `cni-podman9` network +Delete the `podman9` network ``` -# podman network rm cni-podman9 -Deleted: cni-podman9 +# podman network rm podman9 +Deleted: podman9 ``` Delete the `fred` network and all containers associated with the network. diff --git a/docs/source/markdown/podman-network.1.md b/docs/source/markdown/podman-network.1.md index bc75cce3b..f58bd5d5c 100644 --- a/docs/source/markdown/podman-network.1.md +++ b/docs/source/markdown/podman-network.1.md @@ -27,7 +27,7 @@ so networks have to be created again after a backend change. | create | [podman-network-create(1)](podman-network-create.1.md) | Create a Podman network | | disconnect | [podman-network-disconnect(1)](podman-network-disconnect.1.md) | Disconnect a container from a network | | exists | [podman-network-exists(1)](podman-network-exists.1.md) | Check if the given network exists | -| inspect | [podman-network-inspect(1)](podman-network-inspect.1.md) | Displays the raw network configuration for one or more networks | +| inspect | [podman-network-inspect(1)](podman-network-inspect.1.md) | Displays the network configuration for one or more networks | | ls | [podman-network-ls(1)](podman-network-ls.1.md) | Display a summary of networks | | prune | [podman-network-prune(1)](podman-network-prune.1.md) | Remove all unused networks | | reload | [podman-network-reload(1)](podman-network-reload.1.md) | Reload network configuration for containers | diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 66341d875..af44b6eb2 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -333,7 +333,7 @@ $ podman play kube demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89. 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` -Please take into account that CNI networks must be created first using podman-network-create(1). +Please take into account that networks must be created first using podman-network-create(1). ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-play(1)](podman-play.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.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-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index bd2421cdf..f6af4daa4 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -214,9 +214,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the pod, setting the alias for all networks that the pod joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the pod, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} `), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a pod will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-hosts** diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 4566a73d0..cb19e929e 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -755,9 +755,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} `), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-healthcheck** diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index 0a6034e7a..05c3a731e 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -32,7 +32,7 @@ port mapping. Depending on the firewall implementation, we have observed firewa ports being opened automatically due to running a container with a port mapping (for example). If container traffic does not seem to work properly, check the firewall and allow traffic on ports the container is using. A common problem is that -reloading the firewall deletes the cni iptables rules resulting in a loss of +reloading the firewall deletes the cni/netavark iptables rules resulting in a loss of network connectivity for rootful containers. Podman v3 provides the podman network reload command to restore this without having to restart the container. @@ -83,7 +83,7 @@ users. But as of Podman version 4.0, rootless users can also use netavark. The user experience of rootless netavark is very akin to a rootful netavark, except that there is no default network configuration provided. You simply need to create a network, and the one will be created as a bridge network. If you would like to switch from -CNI networking to netvaark, you must issue the `podman system reset --force` command. +CNI networking to netavark, you must issue the `podman system reset --force` command. This will delete all of your images, containers, and custom networks. ``` @@ -177,7 +177,7 @@ address, you should continue to use CNI instead of netavark. ``` $ sudo podman network create -d macvlan -o parent=eth0 webnetwork -/etc/cni/net.d/webnetwork.conflist +webnetwork ``` The next step is to ensure that the DHCP CNI plugin is running. This plugin facilitates the DHCP lease from the network. -- cgit v1.2.3-54-g00ecf From c85722eb9f552f2456d33589a1417264369a6366 Mon Sep 17 00:00:00 2001 From: Charlie Doern Date: Mon, 25 Jul 2022 10:21:14 -0400 Subject: pod create --share none should not create infra for podman pod create, when we are not sharing any namespaces there is no point for the infra container. This is especially true since resources have also been decoupled from the container recently. handle this on the cmd level so that we can still create infra if set explicitly resolves #15048 Signed-off-by: Charlie Doern --- cmd/podman/pods/create.go | 6 ++++++ docs/source/markdown/podman-pod-create.1.md | 2 +- test/e2e/pod_infra_container_test.go | 16 ++++++++++++++++ 3 files changed, 23 insertions(+), 1 deletion(-) (limited to 'docs/source/markdown') diff --git a/cmd/podman/pods/create.go b/cmd/podman/pods/create.go index aea8a7229..4f1f66ad6 100644 --- a/cmd/podman/pods/create.go +++ b/cmd/podman/pods/create.go @@ -134,6 +134,12 @@ func create(cmd *cobra.Command, args []string) error { imageName = infraImage } img := imageName + + if !cmd.Flag("infra").Changed && (share == "none" || share == "") { + // we do not want an infra container when not sharing namespaces + createOptions.Infra = false + } + if !createOptions.Infra { if cmd.Flag("no-hosts").Changed { return fmt.Errorf("cannot specify --no-hosts without an infra container") diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index f6af4daa4..843aed357 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -303,7 +303,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the #### **--share**=*namespace* -A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are cgroup, ipc, net, pid, uts. If the option is prefixed with a "+" then the namespace is appended to the default list, otherwise it replaces the default list. Defaults matches Kubernetes default (ipc, net, uts) +A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared and the infra container will not be created unless expiclity specified via **--infra=true**. The namespaces to choose from are cgroup, ipc, net, pid, uts. If the option is prefixed with a "+" then the namespace is appended to the default list, otherwise it replaces the default list. Defaults matches Kubernetes default (ipc, net, uts) #### **--share-parent** diff --git a/test/e2e/pod_infra_container_test.go b/test/e2e/pod_infra_container_test.go index a2e090524..b53630156 100644 --- a/test/e2e/pod_infra_container_test.go +++ b/test/e2e/pod_infra_container_test.go @@ -435,4 +435,20 @@ var _ = Describe("Podman pod create", func() { Expect(session).Should(Exit(0)) Expect(session.OutputToString()).To(ContainSubstring(hostname)) }) + + tests := []string{"", "none"} + for _, test := range tests { + test := test + It("podman pod create --share="+test+" should not create an infra ctr", func() { + session := podmanTest.Podman([]string{"pod", "create", "--share", test}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + + session = podmanTest.Podman([]string{"pod", "inspect", "--format", "{{.NumContainers}}", session.OutputToString()}) + session.WaitWithDefaultTimeout() + Expect(session).Should(Exit(0)) + Expect(session.OutputToString()).Should((Equal("0"))) + }) + } + }) -- cgit v1.2.3-54-g00ecf From 990ef3cf6b837cf46e5961fcc9c23259294e4fcf Mon Sep 17 00:00:00 2001 From: Erik Sjölund Date: Tue, 26 Jul 2022 06:41:28 +0200 Subject: [CI:DOCS] podman-generate-systemd.1.md: document --sdnotify MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Document why the default value for --sdnotify is overridden. Some was included text from https://github.com/containers/podman/issues/15029#issuecomment-1192244755 * Document that --sdnotify=ignore is overridden. Fixes #15029 Co-authored-by: Valentin Rothberg Co-authored-by: Tom Sweeney Signed-off-by: Erik Sjölund --- docs/source/markdown/podman-generate-systemd.1.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index f61fa4523..48388fc2f 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -14,6 +14,13 @@ Generating unit files for a pod requires the pod to be created with an infra con _Note: If you use this command with the remote client, including Mac and Windows (excluding WSL2) machines, you would still have to place the generated units on the remote system. Moreover, please make sure that the XDG_RUNTIME_DIR environment variable is set. If unset, you may set it via `export XDG_RUNTIME_DIR=/run/user/$(id -u)`._ +_Note: The generated `podman run` command contains an `--sdnotify` option with the value taken from the container. +If the container does not have any explicitly set value or the value is set to __ignore__, the value __conmon__ is used. +The reason for overriding the default value __container__ is that almost no container workloads send notify messages. +Systemd would wait for a ready message that never comes, if the value __container__ is used for a container +that does not send notify messages. The use of the default value might have been unintentional by the user, +therefore the overridden default value._ + ### Kubernetes Integration 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: -- cgit v1.2.3-54-g00ecf