Merge pull request #13838 from bwduncan/patch-1

[CI:DOCS] Update troubleshooting.md

1 files changed, 141 insertions, 116 deletions

diff --git a/troubleshooting.md b/troubleshooting.md
index 941d1a322..cf554654b 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -18,8 +18,10 @@ and retry your command before reporting the issue.
 ---
 ### 2) Can't use volume mount, get permission denied
 
+```console
 $ podman run -v ~/mycontent:/content fedora touch /content/file
 touch: cannot touch '/content/file': Permission denied
+```
 
 #### Solution
 
@@ -38,14 +40,18 @@ content label. Shared volume labels allow all containers to read/write content.
 The **Z** option tells Podman to label the content with a private unshared label.
 Only the current container can use a private volume.
 
+```console
 $ podman run -v ~/mycontent:/content:Z fedora touch /content/file
+```
 
 Make sure the content is private for the container.  Do not relabel system directories and content.
 Relabeling system content might cause other confined services on your machine to fail.  For these
 types of containers we recommend having SELinux separation disabled.  The option `--security-opt label=disable`
 will disable SELinux separation for the container.
 
+```console
 $ podman run --security-opt label=disable -v ~:/home/user fedora touch /home/user/file
+```
 
 In cases where the container image runs as a specific, non-root user, though, the
 solution is to fix the user namespace.  This would include container images such as
@@ -53,7 +59,9 @@ the Jupyter Notebook image (which runs as "jovyan") and the Postgres image (whic
 as "postgres").  In either case, use the `--userns` switch to map user namespaces,
 most of the time by using the **keep-id** option.
 
+```console
 $ podman run -v "$PWD":/home/jovyan/work --userns=keep-id jupyter/scipy-notebook
+```
 
 ---
 ### 3) No such image or Bare keys cannot contain ':'
@@ -131,8 +139,11 @@ It is most likely necessary to enable unprivileged pings on the host.
 Be sure the UID of the user is part of the range in the
 `/proc/sys/net/ipv4/ping_group_range` file.
 
-To change its value you can use something like: `sysctl -w
-"net.ipv4.ping_group_range=0 2000000"`.
+To change its value you can use something like:
+
+```console
+# sysctl -w "net.ipv4.ping_group_range=0 2000000"
+```
 
 To make the change persistent, you'll need to add a file in
 `/etc/sysctl.d` that contains `net.ipv4.ping_group_range=0 $MAX_UID`.
@@ -159,8 +170,8 @@ When rootless Podman attempts to execute a container on a non exec home director
 If you are running Podman or Buildah on a home directory that is mounted noexec,
 then they will fail with a message like:
 
-```
-podman run centos:7
+```console
+$ podman run centos:7
 standard_init_linux.go:203: exec user process caused "permission denied"
 ```
 
@@ -170,8 +181,8 @@ Since the administrator of the system set up your home directory to be noexec, y
 
 For example
 
-```
-cat ~/.config/containers/storage.conf
+```console
+$ cat ~/.config/containers/storage.conf
 [storage]
   driver = "overlay"
   runroot = "/run/user/1000"
@@ -203,7 +214,9 @@ container processes to write to the cgroup file system. Turn on this boolean,
 on SELinux separated systems, to allow systemd to run properly in the container.
 Only do this on systems running older versions of Podman.
 
-`setsebool -P container_manage_cgroup true`
+```console
+# setsebool -P container_manage_cgroup true
+```
 
 ### 9) Newuidmap missing when running rootless Podman commands
 
@@ -214,8 +227,8 @@ Rootless Podman requires the newuidmap and newgidmap programs to be installed.
 If you are running Podman or Buildah as a rootless user, you get an error complaining about
 a missing newuidmap executable.
 
-```
-podman run -ti fedora sh
+```console
+$ podman run -ti fedora sh
 command required for rootless mode with multiple IDs: exec: "newuidmap": executable file not found in $PATH
 ```
 
@@ -231,8 +244,8 @@ Rootless Podman requires the user running it to have a range of UIDs listed in /
 
 A user, either via --user or through the default configured for the image, is not mapped inside the namespace.
 
-```
-podman run --rm -ti --user 1000000 alpine echo hi
+```console
+$ podman run --rm -ti --user 1000000 alpine echo hi
 Error: container create failed: container_linux.go:344: starting container process caused "setup user: invalid argument"
 ```
 
@@ -240,38 +253,38 @@ Error: container create failed: container_linux.go:344: starting container proce
 
 Update the /etc/subuid and /etc/subgid with fields for users that look like:
 
-```
-cat /etc/subuid
+```console
+$ cat /etc/subuid
 johndoe:100000:65536
 test:165536:65536
 ```
 
-The format of this file is USERNAME:UID:RANGE
+The format of this file is `USERNAME:UID:RANGE`
 
-* username as listed in /etc/passwd or getpwent.
+* username as listed in `/etc/passwd` or `getpwent`.
 * The initial uid allocated for the user.
 * The size of the range of UIDs allocated for the user.
 
-This means johndoe is allocated UIDS 100000-165535 as well as his standard UID in the
-/etc/passwd file.
+This means johndoe is allocated UIDs 100000-165535 as well as his standard UID in the
+`/etc/passwd` file.
 
-You should ensure that each user has a unique range of uids, because overlapping UIDs,
+You should ensure that each user has a unique range of UIDs, because overlapping UIDs,
 would potentially allow one user to attack another user. In addition, make sure
-that the range of uids you allocate can cover all uids that the container
-requires. For example, if the container has a user with uid 10000, ensure you
+that the range of UIDs you allocate can cover all UIDs that the container
+requires. For example, if the container has a user with UID 10000, ensure you
 have at least 10001 subuids, and if the container needs to be run as a user with
-uid 1000000, ensure you have at least 1000001 subuids.
+UID 1000000, ensure you have at least 1000001 subuids.
 
-You could also use the usermod program to assign UIDs to a user.
+You could also use the `usermod` program to assign UIDs to a user.
 
-If you update either the /etc/subuid or /etc/subgid file, you need to
+If you update either the `/etc/subuid` or `/etc/subgid` file, you need to
 stop all running containers and kill the pause process.  This is done
 automatically by the `system migrate` command, which can also be used
 to stop all the containers and kill the pause process.
 
-```
-usermod --add-subuids 200000-201000 --add-subgids 200000-201000 johndoe
-grep johndoe /etc/subuid /etc/subgid
+```console
+# usermod --add-subuids 200000-201000 --add-subgids 200000-201000 johndoe
+# grep johndoe /etc/subuid /etc/subgid
 /etc/subuid:johndoe:200000:1001
 /etc/subgid:johndoe:200000:1001
 ```
@@ -281,7 +294,7 @@ grep johndoe /etc/subuid /etc/subgid
 When I change the graphroot storage location in storage.conf, the next time I
 run Podman, I get an error like:
 
-```
+```console
 # podman run -p 5000:5000 -it centos bash
 
 bash: error while loading shared libraries: /lib64/libc.so.6: cannot apply additional memory protection after relocation: Permission denied
@@ -293,9 +306,9 @@ and points storage.conf at this directory.
 
 #### Symptom
 
-SELinux blocks containers from using random locations for overlay storage.
+SELinux blocks containers from using arbitrary locations for overlay storage.
 These directories need to be labeled with the same labels as if the content was
-under /var/lib/containers/storage.
+under `/var/lib/containers/storage`.
 
 #### Solution
 
@@ -303,9 +316,9 @@ Tell SELinux about the new containers storage by setting up an equivalence recor
 This tells SELinux to label content under the new path, as if it was stored
 under `/var/lib/containers/storage`.
 
-```
-semanage fcontext -a -e /var/lib/containers /srv/containers
-restorecon -R -v /srv/containers
+```console
+# semanage fcontext -a -e /var/lib/containers /srv/containers
+# restorecon -R -v /srv/containers
 ```
 
 The semanage command above tells SELinux to setup the default labeling of
@@ -326,8 +339,8 @@ If you pull an anonymous image, one that should not require credentials, you can
 an `invalid username/password` error if you have credentials established in the
 authentication file for the target container registry that are no longer valid.
 
-```
-podman run -it --rm docker://docker.io/library/alpine:latest ls
+```console
+$ podman run -it --rm docker://docker.io/library/alpine:latest ls
 Trying to pull docker://docker.io/library/alpine:latest...ERRO[0000] Error pulling image ref //alpine:latest: Error determining manifest MIME type for docker://alpine:latest: unable to retrieve auth token: invalid username/password
 Failed
 Error: unable to pull docker://docker.io/library/alpine:latest: unable to pull image: Error determining manifest MIME type for docker://alpine:latest: unable to retrieve auth token: invalid username/password
@@ -376,7 +389,7 @@ error creating build container: Error committing the finished image: error addin
 Choose one of the following:
   * Setup containers/storage in a different directory, not on an NFS share.
     * Create a directory on a local file system.
-    * Edit `~/.config/containers/containers.conf` and point the `volume_path` option to that local directory. (Copy /usr/share/containers/containers.conf if ~/.config/containers/containers.conf does not exist)
+    * Edit `~/.config/containers/containers.conf` and point the `volume_path` option to that local directory. (Copy `/usr/share/containers/containers.conf` if `~/.config/containers/containers.conf` does not exist)
   * Otherwise just run Podman as root, via `sudo podman`
 
 ### 15) Rootless 'podman build' fails when using OverlayFS:
@@ -386,7 +399,7 @@ when extracting an image.  However, a rootless user does not have the privileges
 
 #### Symptom
 ```console
-podman build --storage-driver overlay .
+$ podman build --storage-driver overlay .
 STEP 1: FROM docker.io/ubuntu:xenial
 Getting image source signatures
 Copying blob edf72af6d627 done
@@ -411,13 +424,12 @@ Choose one of the following:
 
 ### 16) RHEL 7 and CentOS 7 based `init` images don't work with cgroup v2
 
-The systemd version shipped in RHEL 7 and CentOS 7 doesn't have support for cgroup v2.  Support for cgroup V2 requires version 230 of systemd or newer, which
+The systemd version shipped in RHEL 7 and CentOS 7 doesn't have support for cgroup v2.  Support for cgroup v2 requires version 230 of systemd or newer, which
 was never shipped or supported on RHEL 7 or CentOS 7.
 
 #### Symptom
 ```console
-
-sh# podman run --name test -d registry.access.redhat.com/rhel7-init:latest && sleep 10 && podman exec test systemctl status
+# podman run --name test -d registry.access.redhat.com/rhel7-init:latest && sleep 10 && podman exec test systemctl status
 c8567461948439bce72fad3076a91ececfb7b14d469bfa5fbc32c6403185beff
 Failed to get D-Bus connection: Operation not permitted
 Error: non zero exit code: 1: OCI runtime error
@@ -426,10 +438,9 @@ Error: non zero exit code: 1: OCI runtime error
 #### Solution
 You'll need to either:
 
-* configure the host to use cgroup v1
+* configure the host to use cgroup v1. On Fedora you can do:
 
-```
-On Fedora you can do:
+```console
 # dnf install -y grubby
 # grubby --update-kernel=ALL --args=”systemd.unified_cgroup_hierarchy=0"
 # reboot
@@ -449,11 +460,9 @@ Once the user logs out all the containers exit.
 #### Solution
 You'll need to either:
 
-* loginctl enable-linger $UID
-
-or as root if your user has not enough privileges.
-
-* sudo loginctl enable-linger $UID
+```console
+# loginctl enable-linger $UID
+```
 
 ### 18) `podman run` fails with "bpf create: permission denied error"
 
@@ -488,7 +497,7 @@ $ podman system migrate
 
 Original command now returns
 
-```
+```console
 $ podman unshare cat /proc/self/uid_map
 	 0       1000          1
 	 1     100000      65536
@@ -507,12 +516,13 @@ Any access inside the container is rejected with "Permission denied".
 
 #### Solution
 
-The runtime uses `setgroups(2)` hence the process looses all additional groups
+The runtime uses `setgroups(2)` hence the process loses all additional groups
 the non-root user has. Use the `--group-add keep-groups` flag to pass the
 user's supplementary group access into the container. Currently only available
 with the `crun` OCI runtime.
 
 ### 21) A rootless container running in detached mode is closed at logout
+<!-- This is the same as section 17 above and should be deleted -->
 
 When running a container with a command like `podman run --detach httpd` as
 a rootless user, the container is closed upon logout and is not kept running.
@@ -535,14 +545,14 @@ LOGINCTL(1), SYSTEMD(1)
 ### 22) Containers default detach keys conflict with shell history navigation
 
 Podman defaults to `ctrl-p,ctrl-q` to detach from a running containers. The
-bash and zsh shells default to ctrl-p for the displaying of the previous
+bash and zsh shells default to `ctrl-p` for the displaying of the previous
 command.  This causes issues when running a shell inside of a container.
 
 #### Symptom
 
 With the default detach key combo ctrl-p,ctrl-q, shell history navigation
 (tested in bash and zsh) using ctrl-p to access the previous command will not
-display this previous command. Or anything else.  Conmon is waiting for an
+display this previous command, or anything else.  Conmon is waiting for an
 additional character to see if the user wants to detach from the container.
 Adding additional characters to the command will cause it to be displayed along
 with the additional character. If the user types ctrl-p a second time the shell
@@ -553,23 +563,23 @@ display the 2nd to last command.
 The solution to this is to change the default detach_keys. For example in order
 to change the defaults to `ctrl-q,ctrl-q` use the `--detach-keys` option.
 
-```
-podman run -ti --detach-keys ctrl-q,ctrl-q fedora sh
+```console
+$ podman run -ti --detach-keys ctrl-q,ctrl-q fedora sh
 ```
 
 To make this change the default for all containers, users can modify the
 containers.conf file. This can be done simply in your home directory, but adding the
 following lines to users containers.conf
 
-```
-$ cat >> ~/.config/containers/containers.conf < _eof
+```console
+$ cat >> ~/.config/containers/containers.conf << _eof
 [engine]
 detach_keys="ctrl-q,ctrl-q"
 _eof
 ```
 
 In order to effect root running containers and all users, modify the system
-wide defaults in /etc/containers/containers.conf
+wide defaults in `/etc/containers/containers.conf`.
 
 
 ### 23) Container with exposed ports won't run in a pod
@@ -579,7 +589,7 @@ can not be run within a pod.
 
 #### Symptom
 
-```
+```console
 $ podman pod create --name srcview -p 127.0.0.1:3434:3434 -p 127.0.0.1:7080:7080 -p 127.0.0.1:3370:3370                        4b2f4611fa2cbd60b3899b936368c2b3f4f0f68bc8e6593416e0ab8ecb0a3f1d
 
 $ podman run --pod srcview --name src-expose -p 3434:3434 -v "${PWD}:/var/opt/localrepo":Z,ro sourcegraph/src-expose:latest serve /var/opt/localrepo
@@ -601,7 +611,7 @@ In the example from the symptom section, dropping the `-p 3434:3434` would allow
 `podman run` command to complete, and the container as part of the pod would still have
 access to that port.  For example:
 
-```
+```console
 $ podman run --pod srcview --name src-expose -v "${PWD}:/var/opt/localrepo":Z,ro sourcegraph/src-expose:latest serve /var/opt/localrepo
 ```
 
@@ -615,6 +625,7 @@ before they will run with the fuse filesystem in play.
 When trying to run the container images found at quay.io/podman, quay.io/containers
 registry.access.redhat.com/ubi8 or other locations, an error will sometimes be returned:
 
+<!-- this would be better if it showed the command being run, and use ```console markup -->
 ```
 ERRO error unmounting /var/lib/containers/storage/overlay/30c058cdadc888177361dd14a7ed7edab441c58525b341df321f07bc11440e68/merged: invalid argument
 error mounting container "1ae176ca72b3da7c70af31db7434bcf6f94b07dbc0328bc7e4e8fc9579d0dc2e": error mounting build container "1ae176ca72b3da7c70af31db7434bcf6f94b07dbc0328bc7e4e8fc9579d0dc2e": error creating overlay mount to /var/lib/containers/storage/overlay/30c058cdadc888177361dd14a7ed7edab441c58525b341df321f07bc11440e68/merged: using mount program /usr/bin/fuse-overlayfs: fuse: device not found, try 'modprobe fuse' first
@@ -646,7 +657,7 @@ to mount volumes on them.
 Run the container once in read/write mode, Podman will generate all of the FDs on the rootfs, and
 from that point forward you can run with a read-only rootfs.
 
-```
+```console
 $ podman run --rm --rootfs /path/to/rootfs true
 ```
 
@@ -654,13 +665,13 @@ The command above will create all the missing directories needed to run the cont
 
 After that, it can be used in read only mode, by multiple containers at the same time:
 
-```
+```console
 $ podman run --read-only --rootfs /path/to/rootfs ....
 ```
 
 Another option is to use an Overlay Rootfs Mount:
 
-```
+```console
 $ podman run --rootfs /path/to/rootfs:O ....
 ```
 
@@ -685,7 +696,9 @@ This means that CPU limit delegation is not enabled for the current user.
 
 You can verify whether CPU limit delegation is enabled by running the following command:
 
-    cat "/sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers"
+```console
+$ cat "/sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers"
+```
 
 Example output might be:
 
@@ -697,8 +710,10 @@ not have permission to set CPU limits.
 If you want to enable CPU limit delegation for all users, you can create the
 file `/etc/systemd/system/user@.service.d/delegate.conf` with the contents:
 
-    [Service]
-    Delegate=memory pids cpu io
+```ini
+[Service]
+Delegate=memory pids cpu io
+```
 
 After logging out and logging back in, you should have permission to set CPU
 limits.
@@ -724,26 +739,33 @@ You can confirm this is the case by attempting to connect to the host via `podma
 
 Create a new key using a supported algorithm e.g. ecdsa:
 
-`ssh-keygen -t ecdsa -f ~/.ssh/podman`
+```console
+$ ssh-keygen -t ecdsa -f ~/.ssh/podman
+```
 
 Then copy the new id over:
 
-`ssh-copy-id -i ~/.ssh/podman.pub user@host`
+```console
+$ ssh-copy-id -i ~/.ssh/podman.pub user@host
+```
 
 And then re-add the connection (removing the old one if necessary):
 
-`podman-remote system connection add myuser --identity ~/.ssh/podman ssh://user@host/run/user/1000/podman/podman.sock`
+```console
+$ podman-remote system connection add myuser --identity ~/.ssh/podman ssh://user@host/run/user/1000/podman/podman.sock
+```
 
 And now this should work:
 
-`podman-remote info`
+```console
+$ podman-remote info
+```
 
----
 ### 28) Rootless CNI networking fails in RHEL with Podman v2.2.1 to v3.0.1.
 
 A failure is encountered when trying to use networking on a rootless
 container in Podman v2.2.1 through v3.0.1 on RHEL.  This error does not
-occur on other Linux Distributions.
+occur on other Linux distributions.
 
 #### Symptom
 
@@ -757,6 +779,7 @@ an Infra container image for CNI-in-slirp4netns must be created.  The
 instructions for building the Infra container image can be found for
 v2.2.1 [here](https://github.com/containers/podman/tree/v2.2.1-rhel/contrib/rootless-cni-infra),
 and for v3.0.1 [here](https://github.com/containers/podman/tree/v3.0.1-rhel/contrib/rootless-cni-infra).
+
 ### 29) Container related firewall rules are lost after reloading firewalld
 Container network can't be reached after `firewall-cmd --reload` and `systemctl restart firewalld` Running `podman network reload` will fix it but it has to be done manually.
 
@@ -767,7 +790,7 @@ The firewall rules created by podman are lost when the firewall is reloaded.
 [@ranjithrajaram](https://github.com/containers/podman/issues/5431#issuecomment-847758377) has created a systemd-hook to fix this issue
 
 1) For "firewall-cmd --reload", create a systemd unit file with the following
-```
+```ini
 [Unit]
 Description=firewalld reload hook - run a hook script on firewalld reload
 Wants=dbus.service
@@ -780,8 +803,9 @@ ExecStart=/bin/bash -c '/bin/busctl monitor --system --match "interface=org.fedo
 [Install]
 WantedBy=default.target
 ```
+
 2) For "systemctl restart firewalld", create a systemd unit file with the following
-```
+```ini
 [Unit]
 Description=podman network reload
 Wants=firewalld.service
@@ -796,11 +820,12 @@ ExecStart=/usr/bin/podman network reload --all
 [Install]
 WantedBy=default.target
 ```
-However, If you use busctl monitor then you can't get machine-readable output on `RHEL 8`.
+
+However, If you use busctl monitor then you can't get machine-readable output on RHEL 8.
 Since it doesn't have `busctl -j` as mentioned here by [@yrro](https://github.com/containers/podman/issues/5431#issuecomment-896943018).
 
 For RHEL 8, you can use the following one-liner bash script.
-```
+```ini
 [Unit]
 Description=Redo podman NAT rules after firewalld starts or reloads
 Wants=dbus.service
@@ -815,13 +840,13 @@ Restart=Always
 [Install]
 WantedBy=default.target
 ```
-`busctl-monitor` is almost usable in `RHEL 8`, except that it always outputs two bogus events when it starts up,
+`busctl-monitor` is almost usable in RHEL 8, except that it always outputs two bogus events when it starts up,
 one of which is (in its only machine-readable format) indistinguishable from the `NameOwnerChanged` that you get when firewalld starts up.
 This means you would get an extra `podman network reload --all` when this unit starts.
 
 Apart from this, you can use the following systemd service with the python3 code.
 
-```
+```ini
 [Unit]
 Description=Redo podman NAT rules after firewalld starts or reloads
 Wants=dbus.service
@@ -837,7 +862,7 @@ Restart=always
 WantedBy=default.target
 ```
 The code reloads podman network twice when you use `systemctl restart firewalld`.
-```
+```python3
 import dbus
 from gi.repository import GLib
 from dbus.mainloop.glib import DBusGMainLoop
@@ -892,6 +917,7 @@ def signal_listener():
 if __name__ == "__main__":
     signal_listener()
 ```
+
 ### 30) Podman run fails with `ERRO[0000] XDG_RUNTIME_DIR directory "/run/user/0" is not owned by the current user` or `Error: error creating tmpdir: mkdir /run/user/1000: permission denied`.
 
 A failure is encountered when performing `podman run` with a warning `XDG_RUNTIME_DIR is pointing to a path which is not writable. Most likely podman will fail.`
@@ -901,30 +927,30 @@ A failure is encountered when performing `podman run` with a warning `XDG_RUNTIM
 A rootless container is being invoked with cgroup configuration as `cgroupv2` for user with missing or invalid **systemd session**.
 
 Example cases
-```bash
+```console
 # su user1 -c 'podman images'
 ERRO[0000] XDG_RUNTIME_DIR directory "/run/user/0" is not owned by the current user
 ```
-```bash
+```console
 # su - user1 -c 'podman images'
 Error: error creating tmpdir: mkdir /run/user/1000: permission denied
 ```
 
 #### Solution
 
-Podman expects a valid login session for the `rootless+cgroupv2` use-case. Podman execution is expected to fail if the login session is not present. In most cases, podman will figure out a solution on its own but if `XDG_RUNTIME_DIR` is pointing to a path that is not writable execution will most fail. Typical scenarios of such cases are seen when users are trying to use Podman with `su - <user> -c '<podman-command>`, or `sudo -l` and badly configured systemd session.
+Podman expects a valid login session for the `rootless+cgroupv2` use-case. Podman execution is expected to fail if the login session is not present. In most cases, podman will figure out a solution on its own but if `XDG_RUNTIME_DIR` is pointing to a path that is not writable execution will most likely fail. Typical scenarios of such cases are seen when users are trying to use Podman with `su - <user> -c '<podman-command>'`, or `sudo -l` and badly configured systemd session.
 
 Alternatives:
 
 * Execute Podman via __systemd-run__ that will first start a systemd login session:
 
-  ```
-  sudo systemd-run --machine=username@ --quiet --user --collect --pipe --wait podman run --rm docker.io/library/alpine echo hello
+  ```console
+  $ sudo systemd-run --machine=username@ --quiet --user --collect --pipe --wait podman run --rm docker.io/library/alpine echo hello
   ```
 * Start an interactive shell in a systemd login session with the command `machinectl shell <username>@`
   and then run Podman
 
-  ```
+  ```console
   $ sudo -i
   # machinectl shell username@
   Connected to the local host. Press ^] three times within 1s to exit session.
@@ -977,7 +1003,7 @@ from the user's subordinate UID and GID ranges on the host system.
 
 An example
 
-```Text
+```console
 $ mkdir dir1
 $ chmod 777 dir1
 $ podman run --rm -v ./dir1:/dir1:Z \
@@ -995,8 +1021,8 @@ If you want to read, chown, or remove such a file, enter a user
 namespace. Instead of running commands such as `less dir1/a` or `rm dir1/a`, you
 need to prepend the command-line with `podman unshare`, i.e.,
 `podman unshare less dir1/a` or `podman unshare rm dir1/a`. To change the ownership
-of the file _dir1/a_ to your regular user's UID and GID, run `podman unshare chown 0:0 dir1/a`.
-A file having the ownership _0:0_ in the user namespace is owned by the regular
+of the file `dir1/a` to your regular user's UID and GID, run `podman unshare chown 0:0 dir1/a`.
+A file having the ownership `0:0` in the user namespace is owned by the regular
 user on the host. To use Bash features, such as variable expansion and
 globbing, you need to wrap the command with `bash -c`, e.g.
 `podman unshare bash -c 'ls $HOME/dir1/a*'`.
@@ -1008,41 +1034,41 @@ between the container and the host. Let's try it out.
 
 In the example above `ls -l` shows the UID 102002 and GID 102002. Set shell variables
 
-```Text
-$ uid_from_ls = 102002
-$ gid_from_ls = 102002
+```console
+$ uid_from_ls=102002
+$ gid_from_ls=102002
 ```
 
 Set shell variables to the lowest subordinate UID and GID
 
-```Text
+```console
 $ lowest_subuid=$(podman info --format "{{ (index .Host.IDMappings.UIDMap 1).HostID }}")
 $ lowest_subgid=$(podman info --format "{{ (index .Host.IDMappings.GIDMap 1).HostID }}")
 ```
 
 Compute the UID and GID inside the container that map to the owner of the created file on the host.
 
-```Text
+```console
 $ uid=$(( $uid_from_ls - $lowest_subuid + 1))
 $ gid=$(( $gid_from_ls - $lowest_subgid + 1))
 ```
 (In the computation it was assumed that there is only one subuid range and one subgid range)
 
-```Text
+```console
 $ echo $uid
 2003
 $ echo $gid
 2003
 ```
 
-The computation shows that the UID is _2003_ and the GID is _2003_ inside the container.
+The computation shows that the UID is `2003` and the GID is `2003` inside the container.
 This comes as no surprise as this is what was specified before with `--user=2003:2003`,
 but the same computation could be used whenever a username is specified
-or the __--user__ option is not used.
+or the `--user` option is not used.
 
 Run the container again but now with UIDs and GIDs mapped
 
-```Text
+```console
 $ subuidSize=$(( $(podman info --format "{{ range .Host.IDMappings.UIDMap }}+{{.Size }}{{end }}" ) - 1 ))
 $ subgidSize=$(( $(podman info --format "{{ range .Host.IDMappings.GIDMap }}+{{.Size }}{{end }}" ) - 1 ))
 $ mkdir dir1
@@ -1066,18 +1092,17 @@ $ ls -l dir1/a
 $
 ```
 
-In this example the __--user__ option specified a rootless user in the container.
-As the rootless user could also have been specified in the container image, e.g.,
+In this example the `--user` option specified a rootless user in the container.
+As the rootless user could also have been specified in the container image, e.g.
 
-```Text
+```console
 $ podman image inspect --format "user: {{.User}}" IMAGE
 user: hpc
-$
 ```
-the same problem could also occur even without specifying __--user__.
+the same problem could also occur even without specifying `--user`.
 
 Another variant of the same problem could occur when using
-__--user=root:root__ (the default), but where the root user creates non-root owned files
+`--user=root:root` (the default), but where the root user creates non-root owned files
 in some way (e.g by creating them themselves, or switching the effective UID to
 a rootless user and then creates files).
 
@@ -1097,7 +1122,7 @@ permissions of the regular user of the host.
 for files, directories or devices passed in to the container
 with `--device=..`,`--volume=..` or `--mount=..`, e.g.
 
-```Text
+```console
 $ mkdir dir1
 $ chmod 700 dir1
 $ podman run --rm -v ./dir1:/dir1:Z \
@@ -1110,7 +1135,9 @@ ls: cannot open directory '/dir1': Permission denied
 
 We follow essentially the same solution as in the previous
 troubleshooting tip:
- "_Container creates a file that is not owned by the regular UID_"
+
+    Container creates a file that is not owned by the regular UID
+
 but for this problem the container UID and GID can't be as
 easily computed by mere addition and subtraction.
 
@@ -1118,42 +1145,41 @@ In other words, it might be more challenging to find out the UID and
 the GID inside the container that we want to map to the regular
 user on the host.
 
-If the __--user__ option is used together with a numerical UID and GID
+If the `--user` option is used together with a numerical UID and GID
 to specify a rootless user, we already know the answer.
 
-If the __--user__ option is used together with a username and groupname,
-we could look up the UID and GID in the file _/etc/passwd_ of the container.
+If the `--user` option is used together with a username and groupname,
+we could look up the UID and GID in the file `/etc/passwd` of the container.
 
-If the container user is not set via __--user__ but instead from the
+If the container user is not set via `--user` but instead from the
 container image, we could inspect the container image
 
-```Text
+```console
 $ podman image inspect --format "user: {{.User}}" IMAGE
 user: hpc
-$
 ```
 
-and then look it up in _/etc/passwd_ of the container.
+and then look it up in `/etc/passwd` of the container.
 
 If the problem occurs in a container that is started to run as root but later
 switches to an effictive UID of a rootless user, it might be less
 straightforward to find out the UID and the GID. Reading the
-_Containerfile_, _Dockerfile_ or the _/etc/passwd_ could give a clue.
+`Containerfile`, `Dockerfile` or the `/etc/passwd` could give a clue.
 
 To run the container with the rootless container UID and GID mapped to the
 user's regular UID and GID on the host follow these steps:
 
-Set the _uid_ and _gid_ shell variables in a Bash shell to the UID and GID
+Set the `uid` and `gid` shell variables in a Bash shell to the UID and GID
 of the user that will be running inside the container, e.g.
 
-```Text
+```console
 $ uid=2003
 $ gid=2003
 ```
 
 and run
 
-```Text
+```console
 $ mkdir dir1
 $ echo hello > dir1/file.txt
 $ chmod 700 dir1/file.txt
@@ -1170,13 +1196,12 @@ $ podman run --rm \
   --gidmap $(($gid+1)):$(($gid+1)):$(($subgidSize-$gid)) \
   docker.io/library/alpine cat /dir1/file.txt
 hello
-$
 ```
 
 A side-note: Using [__--userns=keep-id__](https://docs.podman.io/en/latest/markdown/podman-run.1.html#userns-mode)
 can sometimes be an alternative solution, but it forces the regular
 user's host UID to be mapped to the same UID inside the container
-so it provides less flexibility than using __--uidmap__ and __--gidmap__.
+so it provides less flexibility than using `--uidmap` and `--gidmap`.
 
 ### 35) Images in the additional stores can be deleted even if there are containers using them