Merge pull request #23758 from edsantiago/podman-troubleshooting

Create a podman-troubleshooting man page

Makefile

@@ -95,7 +95,7 @@ OCI_RUNTIME ?= ""
 MANPAGES_SOURCE_DIR = docs/source/markdown
 MANPAGES_MD_IN ?= $(wildcard $(MANPAGES_SOURCE_DIR)/*.md.in)
 MANPAGES_MD_GENERATED ?= $(MANPAGES_MD_IN:%.md.in=%.md)
-MANPAGES_MD ?= $(sort $(wildcard $(MANPAGES_SOURCE_DIR)/*.md) $(MANPAGES_MD_GENERATED))
+MANPAGES_MD ?= $(sort $(wildcard $(MANPAGES_SOURCE_DIR)/*.md) $(MANPAGES_MD_GENERATED) $(MANPAGES_SOURCE_DIR)/podman-troubleshooting.7.md)
 MANPAGES ?= $(MANPAGES_MD:%.md=%)
 MANPAGES_DEST ?= $(subst markdown,man, $(subst source,build,$(MANPAGES)))
 
@@ -523,15 +523,19 @@ pkg/api/swagger.yaml: .install.swagger
 $(MANPAGES_MD_GENERATED): %.md: %.md.in $(MANPAGES_SOURCE_DIR)/options/*.md
 	hack/markdown-preprocess
 
+$(MANPAGES_SOURCE_DIR)/podman-troubleshooting.7.md: troubleshooting.md
+	( echo "% podman-troubleshooting 7"; echo; sed -e '/logo.*\.png/d' <$< ) >$@.tmp.$$ && \
+		mv $@.tmp.$$ $@
+
 $(MANPAGES): OUTFILE=$(subst source/markdown,build/man,$@)
 $(MANPAGES): %: %.md .install.md2man docdir
 
 # This does a bunch of filtering needed for man pages:
-#  1. Strip markdown link targets like '[podman(1)](podman.1.md)'
+#  1. Convert all markdown site links to plain text:
+#           [foo](https://www.....)   ->   foo
+#  2. Strip man-page targets like '[podman(1)](podman.1.md)'
 #     to just '[podman(1)]', because man pages have no link mechanism;
-#  2. Then remove the brackets: '[podman(1)]' -> 'podman(1)';
-#  3. Then do the same for all other markdown links,
-#     like '[cgroups(7)](https://.....)'  -> just 'cgroups(7)';
+#  3. Then remove the brackets: '[podman(1)]' -> 'podman(1)';
 #  4. Remove HTML-ish stuff like '<sup>..</sup>' and '<a>..</a>'
 #  5. Replace "\" (backslash) at EOL with two spaces (no idea why)
 # Then two sanity checks:
@@ -545,11 +549,11 @@ $(MANPAGES): %: %.md .install.md2man docdir
 #     ASCII art. I (esm) believe the cost of releasing corrupt man pages
 #     is higher than the cost of carrying this kludge.
 #
-	@$(SED) -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g'    \
-	       -e 's/\[\(podman[^]]*\)\]/\1/g'              \
-	       -e 's/\[\([^]]*\)](http[^)]\+)/\1/g'         \
-	       -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g'    \
-	       -e 's/\\$$/  /g' $<                         |\
+	@$(SED) -e 's/\[\([^]]*\)](http[^)]\+)/\1/g'         \
+	        -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g'     \
+	        -e 's/\[\(podman[^]]*\)\]/\1/g'              \
+	        -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g'    \
+	        -e 's/\\$$/  /g' $<                         |\
 	$(GOMD2MAN) -out $(OUTFILE)
 	@if grep 'included file options/' $(OUTFILE); then \
 		echo "FATAL: man pages must not contain ^^^^ in $(OUTFILE)"; exit 1; \
@@ -910,10 +914,12 @@ install.modules-load: # This should only be used by distros which might use ipta
 install.man:
 	install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man1
 	install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man5
+	install ${SELINUXOPT} -d -m 755 $(DESTDIR)$(MANDIR)/man7
 	install ${SELINUXOPT} -m 644 $(filter %.1,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man1
 	install ${SELINUXOPT} -m 644 docs/source/markdown/links/*1 $(DESTDIR)$(MANDIR)/man1
 	install ${SELINUXOPT} -m 644 $(filter %.5,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man5
 	install ${SELINUXOPT} -m 644 docs/source/markdown/links/*5 $(DESTDIR)$(MANDIR)/man5
+	install ${SELINUXOPT} -m 644 $(filter %.7,$(MANPAGES_DEST)) $(DESTDIR)$(MANDIR)/man7
 
 .PHONY: install.completions
 install.completions:

docs/Makefile

@@ -15,7 +15,7 @@ help:
 
 clean:
 	$(RM) -fr build
-	cd source/markdown && $(RM) -f $$(<.gitignore)
+	cd source/markdown && $(RM) -f $$(<.gitignore) podman-troubleshooting.7.md
 
 .PHONY: help Makefile
 

docs/source/markdown/.gitignore

@@ -58,6 +58,7 @@ podman-start.1.md
 podman-stats.1.md
 podman-stop.1.md
 podman-top.1.md
+podman-troubleshooting.7.md
 podman-unmount.1.md
 podman-unpause.1.md
 podman-update.1.md

docs/source/markdown/podman-build.1.md.in

@@ -709,6 +709,11 @@ useradd to stop creating the lastlog file.
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/man/runc.8.md)**, **[useradd(8)](https://www.unix.com/man-page/redhat/8/useradd)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[Containerfile(5)](https://github.com/containers/common/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/common/blob/main/docs/containerignore.5.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 Aug 2020, Additional options and .containerignore added by Dan Walsh `<[email protected]>`
 

docs/source/markdown/podman-commit.1.md

@@ -125,5 +125,10 @@ $ podman commit -q --change LABEL=io.containers.capabilities=setuid,setgid epic_
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 December 2017, Originally compiled by Urvashi Mohnani <[email protected]>

docs/source/markdown/podman-images.1.md.in

@@ -243,5 +243,10 @@ docker.io/library/alpine   latest   3fd9065eaf02   5 months ago    4.41 MB
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 March 2017, Originally compiled by Dan Walsh `<[email protected]>`

docs/source/markdown/podman-machine.1.md

@@ -39,5 +39,10 @@ environment variable while the machines are running can lead to unexpected behav
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-machine-info(1)](podman-machine-info.1.md)**, **[podman-machine-init(1)](podman-machine-init.1.md)**, **[podman-machine-list(1)](podman-machine-list.1.md)**, **[podman-machine-os(1)](podman-machine-os.1.md)**, **[podman-machine-rm(1)](podman-machine-rm.1.md)**, **[podman-machine-ssh(1)](podman-machine-ssh.1.md)**, **[podman-machine-start(1)](podman-machine-start.1.md)**, **[podman-machine-stop(1)](podman-machine-stop.1.md)**, **[podman-machine-inspect(1)](podman-machine-inspect.1.md)**, **[podman-machine-reset(1)](podman-machine-reset.1.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 March 2021, Originally compiled by Ashley Cui <[email protected]>

docs/source/markdown/podman-pod-create.1.md.in

@@ -226,6 +226,10 @@ $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **containers.conf(1)**, **[cgroups(7)](https://man7.org/linux/man-pages/man7/cgroups.7.html)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
 
 ## HISTORY
 July 2018, Originally compiled by Peter Hunt <[email protected]>

docs/source/markdown/podman-pull.1.md.in

@@ -218,5 +218,10 @@ $ podman --remote pull -q --retry 6 --retry-delay 10s ubi9
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-push(1)](podman-push.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 July 2017, Originally compiled by Urvashi Mohnani <[email protected]>

docs/source/markdown/podman-push.1.md.in

@@ -160,3 +160,8 @@ Storing signatures
 
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-pull(1)](podman-pull.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)**
+
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.

docs/source/markdown/podman-remote.1.md

@@ -194,3 +194,8 @@ Podman uses builtin defaults if no containers.conf file is found.
 
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-system-service(1)](podman-system-service.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**
+
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.

docs/source/markdown/podman-run.1.md.in

@@ -904,6 +904,11 @@ NOTE: Use the environment variable `TMPDIR` to change the temporary storage loca
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 September 2018, updated by Kunal Kushwaha `<[email protected]>`
 

docs/source/markdown/podman.1.md

@@ -466,10 +466,13 @@ The Overlay file system (OverlayFS) is not supported with kernels prior to 5.12.
 
 The Network File System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not supported when running in rootless mode as these file systems do not understand user namespace.  However, rootless Podman can make use of an NFS Homedir by modifying the `$HOME/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage.
 
-For more information, see the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/main/troubleshooting.md).
-
 ## SEE ALSO
 **[containers-mounts.conf(5)](https://github.com/containers/common/blob/main/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **oci-hooks(5)**, **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
 
+### Troubleshooting
+
+See [podman-troubleshooting(7)](https://github.com/containers/podman/blob/main/troubleshooting.md)
+for solutions to common issues.
+
 ## HISTORY
 Dec 2016, Originally compiled by Dan Walsh <[email protected]>

hack/xref-helpmsgs-manpages

@@ -599,6 +599,10 @@ sub podman_man {
         elsif ($line =~ /^\#\#\s+SEE\s+ALSO/) {
             $section = 'see-also';
         }
+        # New section or subsection within SEE ALSO: disable the '**' rules.
+        elsif ($line =~ /^\#\#+/ && $section eq 'see-also') {
+            $section = '';
+        }
         elsif ($line =~ /^\#\#[^#]/) {
             $section = '';
         }

rpm/podman.spec

@@ -274,7 +274,7 @@ PODMAN_VERSION=%{version} %{__make} DESTDIR=%{buildroot} PREFIX=%{_prefix} ETCDI
 sed -i 's;%{buildroot};;g' %{buildroot}%{_bindir}/docker
 
 # do not include docker and podman-remote man pages in main package
-for file in `find %{buildroot}%{_mandir}/man[15] -type f | sed "s,%{buildroot},," | grep -v -e %{name}sh.1 -e remote -e docker`; do
+for file in `find %{buildroot}%{_mandir}/man[157] -type f | sed "s,%{buildroot},," | grep -v -e %{name}sh.1 -e remote -e docker`; do
     echo "$file*" >> %{name}.file-list
 done