From d964d1d7d0a8805e9a2cdf63b5124846e5301897 Mon Sep 17 00:00:00 2001
From: Colin Watson <cjwatson@ubuntu.com>
Date: Thu, 3 Jan 2013 10:32:57 +0000
Subject: [PATCH 079/482] * 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.2.1