* docs/grub.texi (Invoking grub-mount): New section.

Reported by: Filipus Klutiero.  Fixes Debian bug #666427.

ChangeLog

@@ -1,3 +1,8 @@
+2013-01-03  Colin Watson  <cjwatson@ubuntu.com>
+
+	* docs/grub.texi (Invoking grub-mount): New section.
+	Reported by: Filipus Klutiero.  Fixes Debian bug #666427.
+
 2013-01-02  Colin Watson  <cjwatson@ubuntu.com>
 
 	* grub-core/tests/lib/test.c (grub_test_run): Return non-zero on

docs/grub.texi

@@ -20,7 +20,7 @@
 This manual is for GNU GRUB (version @value{VERSION},
 @value{UPDATED}).
 
-Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012,2013 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -37,6 +37,7 @@ Invariant Sections.
 * grub-mkconfig: (grub)Invoking grub-mkconfig.  Generate GRUB configuration
 * grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
 * grub-mkrescue: (grub)Invoking grub-mkrescue.  Make a GRUB rescue image
+* grub-mount: (grub)Invoking grub-mount.        Mount a file system using GRUB
 * grub-probe: (grub)Invoking grub-probe.        Probe device information
 @end direntry
 
@@ -101,6 +102,7 @@ This edition documents version @value{VERSION}.
 * Invoking grub-mkpasswd-pbkdf2::
                                 Generate GRUB password hashes
 * Invoking grub-mkrescue::      Make a GRUB rescue image
+* Invoking grub-mount::         Mount a file system using GRUB
 * Invoking grub-probe::         Probe device information for GRUB
 * Obtaining and Building GRUB:: How to obtain and build GRUB
 * Reporting bugs::              Where you should send a bug report
@@ -4830,6 +4832,93 @@ built-in default.
 @end table
 
 
+@node Invoking grub-mount
+@chapter Invoking grub-mount
+
+The program @command{grub-mount} performs a read-only mount of any file
+system or file system image that GRUB understands, using GRUB's file system
+drivers via FUSE.  (It is only available if FUSE development files were
+present when GRUB was built.)  This has a number of uses:
+
+@itemize @bullet
+@item
+It provides a convenient way to check how GRUB will view a file system at
+boot time.  You can use normal command-line tools to compare that view with
+that of your operating system, making it easy to find bugs.
+
+@item
+It offers true read-only mounts.  Linux does not have these for journalling
+file systems, because it will always attempt to replay the journal at mount
+time; while you can temporarily mark the block device read-only to avoid
+this, that causes the mount to fail.  Since GRUB intentionally contains no
+code for writing to file systems, it can easily provide a guaranteed
+read-only mount mechanism.
+
+@item
+It allows you to examine any file system that GRUB understands without
+needing to load additional modules into your running kernel, which may be
+useful in constrained environments such as installers.
+
+@item
+Since it can examine file system images (contained in regular files) just as
+easily as file systems on block devices, you can use it to inspect any file
+system image that GRUB understands with only enough privileges to use FUSE,
+even if nobody has yet written a FUSE module specifically for that file
+system type.
+@end itemize
+
+Using @command{grub-mount} is normally as simple as:
+
+@example
+grub-mount /dev/sda1 /mnt
+@end example
+
+@command{grub-mount} must be given one or more images and a mount point as
+non-option arguments (if it is given more than one image, it will treat them
+as a RAID set), and also accepts the following options:
+
+@table @option
+@item --help
+Print a summary of the command-line options and exit.
+
+@item --version
+Print the version number of GRUB and exit.
+
+@item -C
+@itemx --crypto
+Mount encrypted devices, prompting for a passphrase if necessary.
+
+@item -d @var{string}
+@itemx --debug=@var{string}
+Show debugging output for conditions matching @var{string}.
+
+@item -K prompt|@var{file}
+@itemx --zfs-key=prompt|@var{file}
+Load a ZFS encryption key.  If you use @samp{prompt} as the argument,
+@command{grub-mount} will read a passphrase from the terminal; otherwise, it
+will read key material from the specified file.
+
+@item -r @var{device}
+@itemx --root=@var{device}
+Set the GRUB root device to @var{device}.  You do not normally need to set
+this; @command{grub-mount} will automatically set the root device to the
+root of the supplied file system.
+
+If @var{device} is just a number, then it will be treated as a partition
+number within the supplied image.  This means that, if you have an image of
+an entire disk in @file{disk.img}, then you can use this command to mount
+its second partition:
+
+@example
+grub-mount -r 2 disk.img mount-point
+@end example
+
+@item -v
+@itemx --verbose
+Print verbose messages.
+@end table
+
+
 @node Invoking grub-probe
 @chapter Invoking grub-probe