From 76eb06330f9e88cab6d19449f13e4aecba21027a Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 13 Sep 2022 09:30:48 -0600 Subject: Man pages: refactor common options: --tls-verify Ugh. This had about five different variations among twelve files. I went with the version from podman-create, kube play, login, pull, push, run. The others: - manifest-add and create did not include the "true, false, missing" text. Now they do. (If this text is N/A to these two, please yell). Also, these two were written with "talking" instead of "contacting" the registry. - podman-build had "does not work with remote", but this does not seem to be true, so I removed it. None of the other files had that. - the wording in podman-search is just weird, with "if needed" and "is listed" and unclear "insecure registries". I just nuked it all. If that wording was deliberate, for some reason that applies only to podman-search, please yell. - podman-container-runlabel has one diff that I like, actually spelling out containers-registries.conf(5), but incorporating that would make this even harder to review. I will add that to my in-progress doc-cleanup PR. Review recommendation: run hack/markdown-preprocess-review but just quit out of it immediately (on both popups). Ignore it completely. Then cd /tmp/markdown-preprocess-review.diffs/tls-verify and run $ clear;for i in podman-*;do echo;echo $i;wdiff -t $i zzz-chosen.md;done This will show the major diffs between each version and the chosen one. Assumes you have wdiff installed. If you have another colorize-actual- individual-word-diffs tool installed, use that. I like cdif[1]. [1] https://github.com/kaz-utashiro/sdif-tools Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 1 + docs/source/markdown/options/tls-verify.md | 5 ++ docs/source/markdown/podman-build.1.md.in | 5 +- .../markdown/podman-container-runlabel.1.md.in | 4 +- docs/source/markdown/podman-create.1.md.in | 4 +- docs/source/markdown/podman-kube-play.1.md.in | 6 +-- docs/source/markdown/podman-login.1.md.in | 6 +-- docs/source/markdown/podman-manifest-add.1.md.in | 4 +- docs/source/markdown/podman-manifest-create.1.md | 55 ---------------------- .../source/markdown/podman-manifest-create.1.md.in | 53 +++++++++++++++++++++ docs/source/markdown/podman-manifest-push.1.md.in | 4 +- docs/source/markdown/podman-pull.1.md.in | 6 +-- docs/source/markdown/podman-push.1.md.in | 6 +-- docs/source/markdown/podman-run.1.md.in | 4 +- docs/source/markdown/podman-search.1.md.in | 7 +-- 15 files changed, 70 insertions(+), 100 deletions(-) create mode 100644 docs/source/markdown/options/tls-verify.md delete mode 100644 docs/source/markdown/podman-manifest-create.1.md create mode 100644 docs/source/markdown/podman-manifest-create.1.md.in (limited to 'docs/source') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 74e7fc075..552e6f520 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -11,6 +11,7 @@ podman-login.1.md podman-logout.1.md podman-logs.1.md podman-manifest-add.1.md +podman-manifest-create.1.md podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md diff --git a/docs/source/markdown/options/tls-verify.md b/docs/source/markdown/options/tls-verify.md new file mode 100644 index 000000000..e3d6f491f --- /dev/null +++ b/docs/source/markdown/options/tls-verify.md @@ -0,0 +1,5 @@ +#### **--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, +then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index ab31c492c..2c636069f 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -627,10 +627,7 @@ timestamp. If the only instruction in a Containerfile is `FROM`, this flag has no effect. -#### **--tls-verify** - -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) +@@option tls-verify #### **--ulimit**=*type=soft-limit[:hard-limit]* diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in index 36e021ce4..bdbd306f2 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md.in +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -55,9 +55,7 @@ Suppress output information when pulling images If a container exists of the default or given name, as needed it will be stopped, deleted and a new container will be created from this image. -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in containers-registries.conf(5). +@@option tls-verify ## EXAMPLES diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 99eebeccb..54afe3b16 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -442,9 +442,7 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the @@option timeout -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify @@option tmpfs diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 6bf3acc9b..e4e1199e6 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -219,11 +219,7 @@ Directory path for seccomp profiles (default: "/var/lib/kubelet/seccomp"). (This Start the pod after creating it, set to false to only create it. -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify @@option userns.container ## EXAMPLES diff --git a/docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md.in index c309395fb..63798ed99 100644 --- a/docs/source/markdown/podman-login.1.md.in +++ b/docs/source/markdown/podman-login.1.md.in @@ -48,11 +48,7 @@ Password for registry Take the password from stdin -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify #### **--username**, **-u**=*username* diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index 0d957cd1e..6a9df69b4 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -56,9 +56,7 @@ configuration information. Specify the OS version which the list or index records as a requirement for the image. This option is rarely used. -#### **--tls-verify** - -Require HTTPS and verify certificates when talking to container registries (defaults to true). +@@option tls-verify #### **--variant** diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md deleted file mode 100644 index cb8ad41fb..000000000 --- a/docs/source/markdown/podman-manifest-create.1.md +++ /dev/null @@ -1,55 +0,0 @@ -% podman-manifest-create 1 - -## NAME -podman\-manifest\-create - Create a manifest list or image index - -## SYNOPSIS -**podman manifest create** [*options*] *listnameorindexname* [*imagename* ...] - -## DESCRIPTION - -Creates a new manifest list and stores it as an image in local storage using -the specified name. - -If additional images are specified, they are added to the newly-created list or -index. - -## OPTIONS - -#### **--all** - -If any of the images which should be added to the new list or index are -themselves lists or indexes, add all of their contents. By default, only one -image from such a list will be added to the newly-created list or index. - -#### **--amend**, **-a** - -If a manifest list named *listnameorindexname* already exists, modify the -preexisting list instead of exiting with an error. The contents of -*listnameorindexname* are not modified if no *imagename*s are given. - -#### **--tls-verify** - -Require HTTPS and verify certificates when talking to container registries. (defaults to true) - -## EXAMPLES - -``` -podman manifest create mylist:v1.11 -9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f -podman manifest create --amend mylist:v1.11 -9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f -``` - -``` -podman manifest create mylist:v1.11 docker://fedora -5c2bc76bfb4ba6665a7973f7e1c05ee0536b4580637f27adc9fa5a4b2bc03cf1 -``` - -``` -podman manifest create --all mylist:v1.11 docker://fedora -30330571e79c65288a4fca421d9aed29b0210d57294d9c2056743fdcf6e3967b -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-manifest-create.1.md.in b/docs/source/markdown/podman-manifest-create.1.md.in new file mode 100644 index 000000000..6ebf8a055 --- /dev/null +++ b/docs/source/markdown/podman-manifest-create.1.md.in @@ -0,0 +1,53 @@ +% podman-manifest-create 1 + +## NAME +podman\-manifest\-create - Create a manifest list or image index + +## SYNOPSIS +**podman manifest create** [*options*] *listnameorindexname* [*imagename* ...] + +## DESCRIPTION + +Creates a new manifest list and stores it as an image in local storage using +the specified name. + +If additional images are specified, they are added to the newly-created list or +index. + +## OPTIONS + +#### **--all** + +If any of the images which should be added to the new list or index are +themselves lists or indexes, add all of their contents. By default, only one +image from such a list will be added to the newly-created list or index. + +#### **--amend**, **-a** + +If a manifest list named *listnameorindexname* already exists, modify the +preexisting list instead of exiting with an error. The contents of +*listnameorindexname* are not modified if no *imagename*s are given. + +@@option tls-verify + +## EXAMPLES + +``` +podman manifest create mylist:v1.11 +9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f +podman manifest create --amend mylist:v1.11 +9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f +``` + +``` +podman manifest create mylist:v1.11 docker://fedora +5c2bc76bfb4ba6665a7973f7e1c05ee0536b4580637f27adc9fa5a4b2bc03cf1 +``` + +``` +podman manifest create --all mylist:v1.11 docker://fedora +30330571e79c65288a4fca421d9aed29b0210d57294d9c2056743fdcf6e3967b +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in index e3d578d10..fe0a534c9 100644 --- a/docs/source/markdown/podman-manifest-push.1.md.in +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -59,9 +59,7 @@ Sign the pushed images with a sigstore signature using a private key at the spec If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. -#### **--tls-verify** - -Require HTTPS and verify certificates when talking to container registries. (defaults to true) +@@option tls-verify ## DESTINATION diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 6c2806a54..46adec97b 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -71,11 +71,7 @@ Print the usage statement. Suppress output information when pulling images -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify #### **--variant**=*VARIANT* diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index 6e6eecfa2..c679950f7 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -90,11 +90,7 @@ Add a sigstore signature at the destination using a private key at the specified If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify ## EXAMPLE diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index a84584072..fe947b1d0 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -481,9 +481,7 @@ Sets whether the signals sent to the **podman run** command are proxied to the c @@option timeout -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +@@option tls-verify @@option tmpfs diff --git a/docs/source/markdown/podman-search.1.md.in b/docs/source/markdown/podman-search.1.md.in index 102cf7ad7..89df8c29f 100644 --- a/docs/source/markdown/podman-search.1.md.in +++ b/docs/source/markdown/podman-search.1.md.in @@ -87,12 +87,7 @@ The result contains the Image name and its tag, one line for every tag associate Do not truncate the output (default *false*). -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified, -default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default -registry is listed in the insecure registries. +@@option tls-verify ## EXAMPLES -- cgit v1.2.3-54-g00ecf