Re: Full documentation for GRUB2

[Colin Watson]

On Wed, Mar 30, 2011 at 07:15:37PM -0600, Leslie Rhorer wrote:
> Colin Watson wrote:
> > That's a reasonable point, thanks.  I've added this text to the "Simple
> > configuration" node:
> > 
> >      `grub-mkconfig' does have some limitations.  While adding extra
> >   custom menu entries to the end of the list can be done by editing
> >   `/etc/grub.d/40_custom' or creating `/boot/grub/custom.cfg', changing
> >   the order of menu entries or changing their titles may require making
> >   complex changes to shell scripts stored in `/etc/grub.d/'.  This may be
> 
>       Yeah, exactly, or perhaps more accurately, not exactly.  I'm not
> grousing at you or anyone else who has contributed to the very large volume
> of work that has clearly gone into GRUB2,  but digging into the shell
> scripts involved with GRUB 2 can be rather daunting.  I say that as someone
> who has far more than a passing familiarity with *nix scripting.

The above paragraph isn't intended to indicate that it's easy to hack
those scripts, just that it's the only option right now if you want to
use grub-mkconfig while doing those things.  I tried to make it clear by
the phrasing that we considered this a problem, too.

> >   improved in the future.  In the meantime, those who feel that it would
> >   be easier to write `grub.cfg' directly are encouraged to do so (*note
> 
>       Easier?  I'm not sure that it is.  More importantly, it may not be
> effective.  In particular it isn't reliably permanent.  Even discounting
> distro upgrades, I can't count the number of times I have had to run
> update-grub or had it run for me.

This is why I said "and to disable any system provided by their
distribution to automatically run `grub-mkconfig'".  I don't think we
can sensibly include details in the upstream distribution.  On
Debian/Ubuntu, you can reliably disable all automatic calls to
update-grub like this:

  dpkg-divert --rename --add /usr/sbin/update-grub
  ln -s /bin/true /usr/sbin/update-grub

(To undo this, 'rm /usr/sbin/update-grub; dpkg-divert --rename --remove
/usr/sbin/update-grub'.)

I've wondered occasionally whether it would be worth it to include
something like GRUB_STATIC in upstream grub-mkconfig; if set, this would
cause grub-mkconfig to do nothing, perhaps printing a message.  This
would mean you wouldn't have to figure out how to disable distribution
facilities that run grub-mkconfig for you; you could just set
GRUB_STATIC=1 and write your own grub.cfg if you wanted.  Vladimir, do
you think you'd take such a change for 1.99?

> Can you say, "Countless Kernel Upgrades"?

That's indeed a situation where grub-mkconfig really helps.
grub-mkconfig was originally written by Debian people, and thus grew out
of the 'update-grub' script shipped in Debian's GRUB Legacy packages.
Debian ships versioned kernel images, and so it's important to keep boot
loader configuration up to date on Debian.

One of the problems with the GRUB Legacy version of update-grub was that
it mixed input and output in a single file.  This had the virtue that
you could edit menu.lst and your changes would be preserved, at least if
you did it the right way; on the other hand, you had to be careful to
edit only parts of that file marked with magic comments, and this
frequently confused users who found that their changes were not as
permanent as they thought.  grub-mkconfig makes a strict separation
between input and output to try to avoid this problem, but that creates
new problems that grub-mkconfig has to support all the different kinds
of configuration you might possibly want.  It's not an easy problem.

> From my reading previously, not to mention what I think I understand of GRUB
> 2's engineering paradigms, I inferred manually editing grub.cfg was not a
> particularly good idea.  For example, one of the tutorials I read when
> making the move from GRUB Legacy was here:
> 
> http://ubuntuforums.org/showthread.php?t=1195275
> 
>       Of course, this does not constitute official documentation, but in
> this tutorial the author repeatedly stresses things such as the following:
> 
> " Manual editing of /boot/grub/grub.cfg is not encouraged. Think of grub.cfg
> as a result, not as an initiator..."
> 
>       What's more, this isn't the only place I have seen such suggestions.
> Such references are easily found, by far not the least (apparently)
> authoritative of which is the text at the very top of the grub.cfg file
> itself:
> 
> #
> # DO NOT EDIT THIS FILE
> #
> # It is automatically generated by grub-mkconfig using templates
> # from /etc/grub.d and settings from /etc/default/grub
> 
>       If you ask me, that seems pretty dismissive of the idea the admin
> should manually edit grub.cfg.

You must not edit grub.cfg if grub-mkconfig is going to overwrite it.
However, if you're in a situation where your boot environment is
relatively static - and there's a pretty decent constituency of people
in such a situation, then there really is absolutely no reason why you
can't write grub.cfg yourself.  For this application, the format is only
about as complicated as that of GRUB Legacy's menu.lst.

> >   Booting::, and *note Shell-like scripting::), and to disable any system
> >   provided by their distribution to automatically run `grub-mkconfig'.
> 
>       That's something of an indigestible tidbit.  First of all, finding
> such a system can be as bad or worse than sifting through the shell scripts
> in /etc/grub.d.

Is the "Booting" section more digestible?  I worried that it didn't
provide enough information, though.  Perhaps "Shell-like scripting"
isn't the best link target here; or maybe it needs a tutorial section
prepended to it.  I wanted a counterpart to "Simple configuration".

> Secondly, ideally there should be a mechanism that allows the admin to
> specify custom aspects of the GRUB configuration that will be
> respected by upgrades and by update-grub and grub-mkconfig.  I realize
> that /etc/default/grub does indeed have some functionality in this
> respect.

I agree, and I'd like to delve into the design work needed for this
after 1.99.

> > (Remember that the biggest thing that often isn't obvious to developers
> > is what their users find non-obvious!)
> 
>       Yeah, OK, sure.  We're all human, and pointing fingers doesn't
> usually get much in the way of useful results.  The answer is for all of us
> to understand and accept each others' limitations and then work to deal with
> them.  Both by constitution and by environmental bias developers are going
> to often be ignorant of what the users don't know and of what the users
> would not immediately think.

Absolutely.  That's why I'm listening to threads such as this one and
trying to make documentation changes to account for them.

> > As Vladimir notes, the documentation does actually already say that you
> > can set the default by menu entry title as well as by number (which
> 
>       OK, I'm going to have to dig for that again...
> 
>       You know what?  I think maybe I did run across this before.  Maybe
> this is utterly obtuse, but what, exactly constitutes the "full name"?  For
> example, in the line:
> 
> menuentry 'Debian GNU/Linux, with Linux 2.6.32-5-amd64 (recovery mode)'
> --class debian --class gnu-linux --class gnu --class os {
> 
>       is the "full name" everything between the quote marks?  Inclusive or
> exclusive of the quote marks?  Heck, although I would not expect it to be
> the case, I suppose it might even be the entire line up to the brace.  Given
> the consequences of screwing up the boot loader (all the systems I have
> running GRUB2 are headless), I'm not very inclined to experiment much.  If I
> were to guess, I would lay odds on " between the quote marks inclusive of
> the quote marks", but I can easily imagine myself being wrong.

I've clarified this and added an example.  Is this clearer?

  http://www.gnu.org/software/grub/manual/grub.html#Simple-configuration

Thanks,

-- 
Colin Watson                                       address@hidden