Fix <65535 IDs available to nested containers

Fixes: #3

Signed-off-by: Chris Evich <cevich@redhat.com>

README.md

@@ -50,7 +50,26 @@ root access on the system.
 $ sudo loginctl enable-linger $USER
 ```
 
-#### Runner registration (step 2)
+#### Expanded user-namespace (step 2)
+
+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
+`65539` IDs like:
+
+`pipglr:<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)`
+
+#### Runner registration (step 3)
 
 All runners must be connected to a project or group runner configuration
 on your gitlab instance (or `gitlab.com`).  This is done using a special
@@ -87,7 +106,7 @@ $ podman container runlabel register $IMAGE
 $ podman secret rm REGISTRATION_TOKEN  # if desired
 ```
 
-#### Runner Configuration (step 3)
+#### Runner Configuration (step 4)
 
 During the registration process (above), a boiler-plate (default) `config.toml` file
 will be created/updated for you.  At this point you may edit the configuration
@@ -103,10 +122,10 @@ $ rm ./config.toml  # if desired
 
 This may be necessary, for example, to increase the default `concurrency` value
 to reflect the number of registered runners.  If you need to edit this file
-after commiting it as a secret, there's
+after committing it as a secret, there's
 [ a `dumpconfig`  *runlabel* for that](README.md#configuration-editing).
 
-#### Volume setup (step 4)
+#### Volume setup (step 5)
 
 Since several users are utilized inside the container volumes must be
 specifically configured to permit access.  This is done using several
@@ -121,10 +140,10 @@ $ podman container runlabel setupcache $IMAGE
 Note: These volumes generally do not contain any critical operational data,
 they may be re-created anytime to quickly free up host disk-space if
 it's running low.  Simply remove them with the command
- `podman volume rm pipglr-storage pipglr-cache`.  The reuse the `setupstorage`
+ `podman volume rm pipglr-storage pipglr-cache`.  Then reuse the `setupstorage`
 and `setupcache` *runlabels* as in the above example.
 
-#### Runner Startup (step 5)
+#### Runner Startup (step 6)
 
 With the runner configuration saved as a Podman secret, and the runner volumes
 created, the GitLab runner container may be launched with the following commands:

setup.sh

@@ -69,9 +69,12 @@ useradd -M -u 1001 -g runner runner
 chmod 770 /home/runner
 
 # Overwrite defaults, only user 'podman' permited to have a user-namespace
-# Split the namespaced ID's around the containers root (ID 0) and the user
-# IDs 1000 and 1001 (defined above) to prevent hijacking from a nested container.
-echo -e "podman:1:999\npodman:1002:64533" | tee /etc/subuid > /etc/subgid
+# Split the namespaced ID's around the containers root (ID 0), podman (ID 1000), and
+# runner (ID 1001) such that the user-namespace of any nested containers cannot
+# read or write any files owned by these users (and/or hijack nested container processes).
+# N/B: The range-end (999+64536) ensures a total of 65535 IDs are available for nested-containers.
+#      This requires the host provide a sufficiently large range, i.e. `pipglr:<start>:65539`
+echo -e "podman:1:999\npodman:1002:64536" | tee /etc/subuid > /etc/subgid
 # Host volume mount necessary for nested-podman to use overlayfs2 for container & volume storage.
 mkdir -p /home/podman/.local/share/containers
 # Nested-container's local container-cache volume mount, recommended by gitlab-runner docs.