vbatts
/
grub
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

* docs/grub.texi (Filesystem): Refer to `search' instead of `find'. 

(password): New section.
(password_pbkdf2): New section.
(search): New section.
(Security): New section.
(Troubleshooting): New section, currently very incomplete.
(Invoking grub-mkpasswd-pbkdf2): New section.
(Internals): New section, currently very incomplete.
This commit is contained in:
Colin Watson 2010-06-07 14:32:12 +01:00
parent e1cbcc40a4
commit 4003dd38df
2 changed files with 326 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
ChangeLog
View File

@ -1,3 +1,14 @@
2010-06-07 Colin Watson <cjwatson@ubuntu.com>
* docs/grub.texi (Filesystem): Refer to `search' instead of `find'.
(password): New section.
(password_pbkdf2): New section.
(search): New section.
(Security): New section.
(Troubleshooting): New section, currently very incomplete.
(Invoking grub-mkpasswd-pbkdf2): New section.
(Internals): New section, currently very incomplete.
2010-06-07 Colin Watson <cjwatson@ubuntu.com>
* util/grub.d/00_header.in: Add some more quoting (of

317
docs/grub.texi
View File

@ -35,6 +35,7 @@ Invariant Sections.
* GRUB: (grub). The GRand Unified Bootloader
* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
* grub-mkconfig: (grub)Invoking grub-mkconfig. Generate GRUB configuration
* grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
@end direntry
@setchapternewpage odd
@ -84,9 +85,12 @@ This edition documents version @value{VERSION}.
* Filesystem:: Filesystem syntax and semantics
* Interface:: The menu and the command-line
* Commands:: The list of available builtin commands
* Security:: Authentication and authorisation
* Troubleshooting:: Error messages produced by GRUB
* Invoking grub-install:: How to use the GRUB installer
* Invoking grub-mkconfig:: Generate a GRUB configuration file
* Invoking grub-mkpasswd-pbkdf2::
Generate GRUB password hashes
* Obtaining and Building GRUB:: How to obtain and build GRUB
* Reporting bugs:: Where you should send a bug report
* Future:: Some future plans on GRUB
@ -1041,8 +1045,8 @@ GRUB uses a special syntax for specifying disk drives which can be
accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
device is equivalent to which OS device. Normally, that will be clear if
you see the files in a device or use the command @command{find}
(@pxref{find}).
you see the files in a device or use the command @command{search}
(@pxref{search}).
@menu
* Device syntax:: How to specify devices
@ -1415,8 +1419,11 @@ you forget a command, you can run the command @command{help}
* keystatus:: Check key modifier status
* ls:: List devices or files
* parttool:: Modify partition table entries
* password:: Set a clear-text password
* password_pbkdf2:: Set a hashed password
* play:: Play a tune
* reboot:: Reboot your computer
* search:: Search devices by file, label, or UUID
* set:: Set an environment variable
* unset:: Unset an environment variable
@end menu
@ -1747,6 +1754,25 @@ Wwindows and multiple primary FAT partitions exist in one disk. See also
@end deffn
@node password
@subsection password
@deffn Command password user clear-password
Define a user named @var{user} with password @var{clear-password}.
@xref{Security}.
@end deffn
@node password_pbkdf2
@subsection password_pbkdf2
@deffn Command password_pbkdf2 user hashed-password
Define a user named @var{user} with password hash @var{hashed-password}.
Use @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
to generate password hashes. @xref{Security}.
@end deffn
@node play
@subsection play
@ -1774,6 +1800,29 @@ Reboot the computer.
@end deffn
@node search
@subsection search
@deffn Command search @
[@option{--file}|@option{--label}|@option{--fs-uuid}] @
[@option{--set} var] [@option{--no-floppy}] name
Search devices by file (@option{-f}, @option{--file}), filesystem label
(@option{-l}, @option{--label}), or filesystem UUID (@option{-u},
@option{--fs-uuid}).
If the @option{--set} option is used, the first device found is set as the
value of environment variable @var{var}. The default variable is
@samp{root}.
The @option{--no-floppy} option prevents searching floppy devices, which can
be slow.
The @samp{search.file}, @samp{search.fs_label}, and @samp{search.fs_uuid}
commands are aliases for @samp{search --file}, @samp{search --label}, and
@samp{search --fs-uuid} respectively.
@end deffn
@node set
@subsection set
@ -1791,6 +1840,135 @@ Unset the environment variable @var{envvar}.
@end deffn
@node Security
@chapter Authentication and authorisation
By default, the boot loader interface is accessible to anyone with physical
access to the console: anyone can select and edit any menu entry, and anyone
can get direct access to a GRUB shell prompt. For most systems, this is
reasonable since anyone with direct physical access has a variety of other
ways to gain full access, and requiring authentication at the boot loader
level would only serve to make it difficult to recover broken systems.
However, in some environments, such as kiosks, it may be appropriate to lock
down the boot loader to require authentication before performing certain
operations.
The @samp{password} (@pxref{password}) and @samp{password_pbkdf2}
(@pxref{password_pbkdf2}) commands can be used to define users, each of
which has an associated password. @samp{password} sets the password in
plain text, requiring @file{grub.cfg} to be secure; @samp{password_pbkdf2}
sets the password hashed using the Password-Based Key Derivation Function
(RFC 2898), requiring the use of @command{grub-mkpasswd-pbkdf2}
(@pxref{Invoking grub-mkpasswd-pbkdf2}) to generate password hashes.
In order to enable authentication support, the @samp{superusers} environment
variable must be set to a list of usernames, separated by any of spaces,
commas, semicolons, pipes, or ampersands. Superusers are permitted to use
the GRUB command line, edit menu entries, and execute any menu entry.
Other users may be given access to specific menu entries by giving a list of
usernames (as above) using the @kbd{--users} option to the @samp{menuentry}
command (@pxref{menuentry}).
Putting this together, a typical @file{grub.cfg} fragment might look like
this:
@example
@group
set superusers="root"
password_pbkdf2 root grub.pbkdf2.sha512.10000.biglongstring
password user1 insecure
menuentry "Superusers only" @{
set root=(hd0,1)
linux /vmlinuz
@}
menuentry "May be run by user1" --users user1 @{
set root=(hd0,2)
chainloader +1
@}
@end group
@end example
The @command{grub-mkconfig} program does not yet have built-in support for
generating configuration files with authentication. You can use
@file{/etc/grub.d/40_custom} to add simple superuser authentication, by
adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
commands.
@node Troubleshooting
@chapter Error messages produced by GRUB
@menu
* GRUB only offers a rescue shell::
@end menu
@node GRUB only offers a rescue shell
@section GRUB only offers a rescue shell
GRUB's normal start-up procedure involves setting the @samp{prefix}
environment variable to a value set in the core image by
@command{grub-install}, setting the @samp{root} variable to match, loading
the @samp{normal} module from the prefix, and running the @samp{normal}
command. This command is responsible for reading
@file{/boot/grub/grub.cfg}, running the menu, and doing all the useful
things GRUB is supposed to do.
If, instead, you only get a rescue shell, this usually means that GRUB
failed to load the @samp{normal} module for some reason. It may be possible
to work around this temporarily: for instance, if the reason for the failure
is that @samp{prefix} is wrong (perhaps it refers to the wrong device, or
perhaps the path to @file{/boot/grub} was not correctly made relative to the
device), then you can correct this and enter normal mode manually:
@example
@group
# Inspect the current prefix:
echo @verb{'${prefix}'}
# Set to the correct value, which might be something like this:
set prefix=(hd0,1)/grub
set root=(hd0,1)
insmod normal
normal
@end group
@end example
However, any problem that leaves you in the rescue shell probably means that
GRUB was not correctly installed. It may be more useful to try to reinstall
it properly using @kbd{grub-install @var{device}} (@pxref{Invoking
grub-install}). When doing this, there are a few things to remember:
@itemize @bullet{}
@item
Drive ordering in your operating system may not be the same as the boot
drive ordering used by your firmware. Do not assume that your first hard
drive (e.g. @samp{/dev/sda}) is the one that your firmware will boot from.
@item
At least on BIOS systems, if you tell @command{grub-install} to install GRUB
to a partition but GRUB has already been installed in the master boot
record, then the GRUB installation in the partition will be ignored.
@item
If possible, it is generally best to avoid installing GRUB to a partition
(unless it is a special partition for the use of GRUB alone, such as the
BIOS Boot Partition used on GPT). Doing this means that GRUB may stop being
able to read its core image due to a file system moving blocks around, such
as while defragmenting, running checks, or even during normal operation.
Installing to the whole disk device is normally more robust.
@item
Check that GRUB actually knows how to read from the device and file system
containing @file{/boot/grub}. It will not be able to read from encrypted
devices, nor from file systems for which support has not yet been added to
GRUB.
@end itemize
@node Invoking grub-install
@chapter Invoking grub-install
@ -1858,6 +2036,34 @@ it to standard output.
@end table
@node Invoking grub-mkpasswd-pbkdf2
@chapter Invoking grub-mkpasswd-pbkdf2
The program @command{grub-mkpasswd-pbkdf2} generates password hashes for
GRUB (@pxref{Security}).
@example
grub-mkpasswd-pbkdf2
@end example
@command{grub-mkpasswd-pbkdf2} accepts the following options:
@table @option
@item -c @var{number}
@itemx --iteration-count=@var{number}
Number of iterations of the underlying pseudo-random function. Defaults to
10000.
@item -l @var{number}
@itemx --buflen=@var{number}
Length of the generated hash. Defaults to 64.
@item -s @var{number}
@itemx --salt=@var{number}
Length of the salt. Defaults to 64.
@end table
@node Obtaining and Building GRUB
@appendix How to obtain and build GRUB
@ -1976,6 +2182,113 @@ a look at @uref{http://www.gnu.org/software/grub/grub.html, the
homepage}.
@node Internals
@appendix Hacking GRUB
@menu
* Getting the source code::
* Finding your way around::
@end menu
@node Getting the source code
@section Getting the source code
GRUB is maintained using the @uref{http://bazaar-vcs.org/, Bazaar revision
control system}. To fetch the primary development branch:
@example
bzr get http://bzr.savannah.gnu.org/r/grub/trunk/grub
@end example
The GRUB developers maintain several other branches with work in progress.
Of these, the most interesting is the experimental branch, which is a
staging area for new code which we expect to eventually merge into trunk but
which is not yet ready:
@example
bzr get http://bzr.savannah.gnu.org/r/grub/branches/experimental
@end example
Once you have used @kbd{bzr get} to fetch an initial copy of a branch, you
can use @kbd{bzr pull} to keep it up to date. If you have modified your
local version, you may need to resolve conflicts when pulling.
@node Finding your way around
@section Finding your way around
Here is a brief map of the GRUB code base.
GRUB uses Autoconf, but not (yet) Automake. The top-level build rules are
in @file{configure.ac}, @file{Makefile.in}, and @file{conf/*.rmk}. Each
@file{conf/*.rmk} file represents a particular target configuration, and is
processed into GNU Make rules by @file{genmk.rb} (which you only need to
look at if you are extending the build system). If you are adding a new
module which follows an existing pattern, such as a new command or a new
filesystem implementation, it is usually easiest to grep @file{conf/*.rmk}
for an existing example of that pattern to find out where it should be
added.
Low-level boot code, such as the MBR implementation on PC BIOS systems, is
in the @file{boot/} directory.
The GRUB kernel is in @file{kern/}. This contains core facilities such as
the device, disk, and file frameworks, environment variable handling, list
processing, and so on. The kernel should contain enough to get up to a
rescue prompt. Header files for kernel facilities, among others, are in
@file{include/}.
Terminal implementations are in @file{term/}.
Disk access code is spread across @file{disk/} (for accessing the disk
devices themselves), @file{partmap/} (for interpreting partition table
data), and @file{fs/} (for accessing filesystems). Note that, with the odd
specialised exception, GRUB only contains code to @emph{read} from
filesystems and tries to avoid containing any code to @emph{write} to
filesystems; this lets us confidently assure users that GRUB cannot be
responsible for filesystem corruption.
PCI and USB bus handling is in @file{bus/}.
Video handling code is in @file{video/}. The graphical menu system uses
this heavily, but is in a separate directory, @file{gfxmenu/}.
Most commands are implemented by files in @file{commands/}, with the
following exceptions:
@itemize
@item
A few core commands live in @file{kern/corecmd.c}.
@item
Commands related to normal mode live under @file{normal/}.
@item
Commands that load and boot kernels live under @file{loader/}.
@item
The @samp{loopback} command is really a disk device, and so lives in
@file{disk/loopback.c}.
@item
The @samp{gettext} command lives under @file{gettext/}.
@item
The @samp{loadfont} and @samp{lsfonts} commands live under @file{font/}.
@item
The @samp{serial}, @samp{terminfo}, and @samp{background_image} commands
live under @file{term/}.
@item
The @samp{efiemu_*} commands live under @file{efiemu/}.
@end itemize
There are a few other special-purpose exceptions; grep for them if they
matter to you.
@node Copying This Manual
@appendix Copying This Manual