From 9a3cdbccd18ddda45d3e69de75d6c4865da72aae Mon Sep 17 00:00:00 2001 From: Colin Watson 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 + + * docs/grub.texi (Invoking grub-mount): New section. + Reported by: Filipus Klutiero. Fixes Debian bug #666427. + 2013-01-02 Colin Watson * 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