From c093d6a845a129bcf459167a30f7d9f2a7ff965d Mon Sep 17 00:00:00 2001
From: Chris Evich <cevich@redhat.com>
Date: Wed, 4 Oct 2023 13:49:24 -0400
Subject: [PATCH] Improve user-namespace docs slightly

Try to explain in more detail and add new error-message possibility.

Signed-off-by: Chris Evich <cevich@redhat.com>
---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 7f86808..c338006 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,9 @@ when running potentially arbitrary CI/CD code.  Though, the ultimate
 responsibility still rests with the end-user to review the setup and
 configuration relative to their own security situation/environment.
 
+**Note**: While this can run entirely under a regular user, it will require
+root access for the first two setup steps (below).
+
 ### Operation
 
 This image leverages the podman `runlabel` feature heavily.  Several
@@ -42,7 +45,7 @@ $ eval $(podman inspect --format=json $IMAGE | jq -r .[].Labels.<label>)
 
 By default on many distributions, regular users aren't permitted to leave
 background processes running after they log out.  Since this is likely
-desired for the user running the pipglr container, `systemd` needs to be
+desired for running the pipglr container long-term, `systemd` needs to be
 configured to override this policy.  For this, you (`$USER`) will need
 root access on the system.
 
@@ -50,24 +53,50 @@ root access on the system.
 $ sudo loginctl enable-linger $USER
 ```
 
-#### Expanded user-namespace (step 2)
+Side-effect: This will allow your user to persist other user-level systemd
+services as well.  For example `podman.socket` is handy to enable for
+`podman remote` access.  You could also [setup
+quadlet](https://www.redhat.com/sysadmin/quadlet-podman) or a systemd unit
+so pipglr starts up on system boot.
 
-Some nested container images need to utilize high UID/GID values
-like `65535`.  However, many distributions set that as the default max
-number of user-namespace IDs.  Since three IDs are needed inside the
-`pipglr` container, a larger range is required on the host.  As root,
-edit the two files `/etc/subuid` and `/etc/subgid` to expand the range.
-For example assuming a local user called `pipglr` is used to run the
-container, the contents of these files should be edited to allocate
+#### Expanded user-namespace (step 2) ***This is probably important***
+
+As an added protection/safety measure, pipglr excludes three UID/GIDs
+from being used by job-level containers.  One for `root`, another for
+`runner` and a third for `podman`.  However, some container images
+you may want to use for jobs (mainly Debian/Ubuntu), assign one/more
+essential users a high UID/GID value (like `65535`).
+
+At the same time, most distributions also set `65536` as the default maximum
+number (including ID `0`) of IDs to allocate for user-namespaces (via `/etc/login.defs`).  This
+creates a problem you won't realize until the runner actually picks up a job
+😞 The main symptom of this issue will be messages in the pipglr containers log,
+similar to (abbreviated):
+
+```
+...cut...
+running `/usr/bin/newuidmap ...cut...`: newuidmap: write to uid_map failed: Operation not permitted
+Error: cannot set up namespace using "/usr/bin/newuidmap": exit status 1
+...cut...
+```
+
+or
+
+```
+E: setgroups 65534 failed - setgroups (22: Invalid argument)
+```
+
+***The good news is, working around this is relatively simple:***
+
+As root, edit the two files `/etc/subuid` and `/etc/subgid` to expand the
+by 3 IDs.  For example assuming a user running the pipglr container is
+called `johndoe`, the contents of these files should be edited to allocate
 `65539` IDs like:
 
-`pipglr:<some number>:65539`
+`jogndoe:<some number>:65539`
 
-Where `<some number>` was set by your OS when the `pipglr` user was created.
-If you don't make this change, you're likely to experience errors starting
-containers for CI jobs, such as:
-
-`E: setgroups 65534 failed - setgroups (22: Invalid argument)`
+Where `<some number>` was set by your OS when the `johndoe` user was created
+(you can ignore this).  Only the last number needs to be increased.
 
 #### Runner registration (step 3)