1 files changed, 19 insertions, 9 deletions
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 7d0aa5001..f1fddb2fc 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -46,7 +46,7 @@ Set the ARCH of the image to the provided value instead of the architecture of t
 **--authfile**=*path*
 
 Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -111,17 +111,27 @@ network namespaces can be found.
 
 **--cpu-period**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) period
+Set the CPU period for the Completely Fair Scheduler (CFS), which is a
+duration in microseconds. Once the container's CPU quota is used up, it will
+not be scheduled to run until the current period ends. Defaults to 100000
+microseconds.
 
-Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify.
+On some systems, changing the CPU limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-quota**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) quota
+Limit the CPU Completely Fair Scheduler (CFS) quota.
 
 Limit the container's CPU usage. By default, containers run with the full
-CPU resource. This flag tell the kernel to restrict the container's CPU usage
-to the quota you specify.
+CPU resource. The limit is a number in microseconds. If you provide a number,
+the container will be allowed to use that much CPU time until the CPU period
+ends (controllable via **--cpu-period**).
+
+On some systems, changing the CPU limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-shares**, **-c**=*shares*
 
@@ -470,7 +480,7 @@ When --timestamp is set, the created timestamp is always set to the time specifi
 
 **--tls-verify**=*true|false*
 
-Require HTTPS and verify certificates when talking to container registries (defaults to true). (Not available for remote commands)
+Require HTTPS and verify certificates when talking to container registries (defaults to true).
 
 **--ulimit**=*type*=*soft-limit*[:*hard-limit*]
 
@@ -787,9 +797,9 @@ registries.conf is the configuration file which specifies which container regist
 
 ## Troubleshooting
 
-If you are using a useradd command within a Containerfile 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.
+### lastlog sparse file
 
-### Solution
+If you are using a useradd command within a Containerfile 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.
 
 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.