Help document using buildah mount in rootless mode

Update man page to show example of using buildah mount
in rootless mode.

Also enhance buildah mount --help to explain the buildah unshare
requirement.

Signed-off-by: Daniel J Walsh <[email protected]>

Closes: #1341
Approved by: TomSweeneyRedHat

cmd/buildah/mount.go

@@ -11,8 +11,14 @@ import (
 
 func init() {
 	var (
-		mountDescription = "\n  Mounts a working container's root filesystem for manipulation."
-		noTruncate       bool
+		mountDescription = `buildah mount
+  mounts a working container's root filesystem for manipulation.
+
+  Note:  In rootless mode you need to first execute buildah unshare, to put you
+  into the usernamespace. Afterwards you can buildah mount the container and
+  view/modify the content in the containers root file system.
+`
+		noTruncate bool
 	)
 	mountCommand := &cobra.Command{
 		Use:   "mount",
@@ -21,9 +27,14 @@ func init() {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return mountCmd(cmd, args, noTruncate)
 		},
-		Example: `buildah mount
+		Example: `  buildah mount
+  buildah mount containerID
+  buildah mount containerID1 containerID2
+
+  In rootless mode you must use buildah unshare first.
+  buildah unshare
   buildah mount containerID
-  buildah mount containerID1 containerID2`,
+`,
 	}
 
 	flags := mountCommand.Flags()

docs/buildah-mount.md

@@ -10,8 +10,7 @@ buildah\-mount - Mount a working container's root filesystem.
 Mounts the specified container's root file system in a location which can be
 accessed from the host, and returns its location.
 
-If the mount command is invoked without any arguments, the tool will list all of the
-currently mounted containers.
+If the mount command is invoked without any arguments, the tool will list all of the currently mounted containers.
 
 When running in rootless mode, mount runs in a different namespace so
 that the mounted volume might not be accessible from the host when
@@ -33,21 +32,35 @@ Do not truncate IDs in output.
 
 ## EXAMPLE
 
+```
 buildah mount c831414b10a3
-
 /var/lib/containers/storage/overlay2/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged
+```
 
+```
 buildah mount
-
 c831414b10a3 /var/lib/containers/storage/overlay2/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged
-
 a7060253093b /var/lib/containers/storage/overlay2/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged
+```
 
+```
 buildah mount efdb54a2f0d7 644db0db094c adffbea87fa8
-
 efdb54a2f0d7 /var/lib/containers/storage/overlay/f8cac5cce73e5102ab321cc5b57c0824035b5cb82b6822e3c86ebaff69fefa9c/merged
 644db0db094c /var/lib/containers/storage/overlay/c3ec418be5bda5b72dca74c4d397e05829fe62ecd577dd7518b5f7fc1ca5f491/merged
 adffbea87fa8 /var/lib/containers/storage/overlay/03a071f206f70f4fcae5379bd5126be86b5352dc2a0c3449cd6fca01b77ea868/merged
+```
+
+If running in rootless mode, you need to do a buildah unshare first to use
+the mount point.
+```
+$ buildah unshare
+# buildah mount efdb54a2f0d7
+efdb54a2f0d7 /var/lib/containers/storage/overlay/f8cac5cce73e5102ab321cc5b57c0824035b5cb82b6822e3c86ebaff69fefa9c/merged
+# cp foobar  /var/lib/containers/storage/overlay/f8cac5cce73e5102ab321cc5b57c0824035b5cb82b6822e3c86ebaff69fefa9c/merged
+# buildah unmount efdb54a2f0d7
+# exit
+$ buildah commit  efdb54a2f0d7 newimage
+```
 
 ## SEE ALSO
-buildah(1)
+buildah(1), buildah-unshare(1), buildah-umount(1)

docs/buildah-umount.md

@@ -23,4 +23,4 @@ buildah umount containerID1 containerID2 containerID3
 buildah umount --all
 
 ## SEE ALSO
-buildah(1)
+buildah(1), buildah-umount(1)

docs/buildah-unshare.md

@@ -1,4 +1,4 @@
-# buildah-unshare "19" "June 2018" "buildah"
+# buildah-unshare "1" "June 2018" "buildah"
 
 ## NAME
 buildah\-unshare - Run a command inside of a modified user namespace.