From 9a3cdbccd18ddda45d3e69de75d6c4865da72aae Mon Sep 17 00:00:00 2001

From: Colin Watson <cjwatson@ubuntu.com>

Date: Thu, 3 Jan 2013 10:32:57 +0000

Subject: [PATCH 078/364] * docs/grub.texi (Invoking grub-mount): New section.

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

---

 ChangeLog      |  5 ++++

 docs/grub.texi | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-

 2 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog

index 0585437..c91fe35 100644

--- a/ChangeLog

+++ b/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

diff --git a/docs/grub.texi b/docs/grub.texi

index e9af377..60b18b5 100644

--- a/docs/grub.texi

+++ b/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

-- 

1.8.1.4