Add troubleshooting for sparse files

A common failure with people building container images is the
creation of large sparse files, particularly useradd creating
the lastlog file.

This PR Documents the failures.

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

2 files changed, 21 insertions, 1 deletions

diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index f887d68cd..76e16b42c 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -614,8 +614,16 @@ $ podman build -f dev/Dockerfile https://10.10.10.1/podman/context.tar.gz
 
 registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
 
+## Troubleshooting
+
+If you are using a useradd command within a Dockerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`.  This can cause the build to hang forever.  Go language does not support sparse files correctly, which can lead to some huge files being created in your container image.
+
+### Solution
+
+If you are using `useradd` within your build script, you should pass the `--no-log-init or -l` option to the `useradd` command.  This option tells useradd to stop creating the lastlog file.
+
 ## SEE ALSO
-podman(1), buildah(1), containers-registries.conf(5)
+podman(1), buildah(1), containers-registries.conf(5), useradd(8)
 
 ## HISTORY
 May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
diff --git a/troubleshooting.md b/troubleshooting.md
index 030f0af7e..4649cccb3 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -127,3 +127,15 @@ To change its value you can use something like: `sysctl -w
 
 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`.
+
+### 5) Build hangs when the Dockerfile contains the useradd command
+
+When the Dockerfile contains a command like RUN useradd -u 99999000 -g users newuser the build can hang.
+
+#### Symptom
+
+If you are using a useradd command within a Dockerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`.  This can cause the build to hang forever.  Go language does not support sparse files correctly, which can lead to some huge files being created in your container image.
+
+#### Solution
+
+If the entry in the Dockerfile looked like: RUN useradd -u 99999000 -g users newuser then add the `--log-no-init` parameter to change it to: `RUN useradd --log-no-init -u 99999000 -g users newuser`. This option tells useradd to stop creating the lastlog file.