Revision 12 as of 2008-01-30 16:35:24

Clear message

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.


/boot/grub/menu.lst is the single file where all boot-time options are configured for installed i386 and amd64 systems. Ubuntu must support package-initiated updates (for installation of new kernel packages) without silently discarding user-initiated config changes.

Release Note

User-modified grub menu.lst files will trigger conflict-resolution dialog on kernel upgrade: previously, if a user edited the bootloader configuration in /boot/grub/menu.lst directly, these changes might be silently lost when a new kernel was installed. The new version of the grub package detects when such changes have been made, and will ask users to resolve this conflict manually when a kernel package is installed.


/boot/grub/menu.lst is the canonical upstream location where changes are made to the configuration for the grub bootloader. Third-party documentation and how-tos will document that users should edit this file in order to make changes to their boot configuration. However, the current behavior of update-grub is to replace the kernel boot stanzas with stanzas auto-generated from magic comments stored at the top of this file. This will overwrite configuration changes made by the user, and may result in a non-working bootloader configuration or a non-working kernel configuration.

This is reported as [ bug #103297] against grub.

Use Cases

  1. Trang knows nothing about kernels or bootloaders, and has never touched /boot/grub/menu.lst. A newer kernel becomes available; it should be installed on her system automatically and become the default.
  2. Lawrence is new to Ubuntu, but has used grub before on other systems. He edits /boot/grub/menu.lst by hand to change the boot options for his kernel, and a kernel update later becomes available. His changes to the boot options should not be overwritten silently.
  3. Barb is an experienced Ubuntu user who has read the comments in the Ubuntu /boot/grub/menu.lst and used the kopt= setting to configure her boot options. She expects that this setting will continue to be applied for newly-installed kernel packages.


  • grub2 will not be a viable solution for 8.04 LTS.
  • keeping magic comments in /boot/grub/menu.lst is better than keeping them in an external file, since existing widely-available documentation will talk about /boot/grub/menu.lst rather than said hypothetical external file


update-grub should manage the auto-generated section of /boot/grub/menu.lst using ucf. This allows storing a baseline for the file contents after each automatic update, so that with the next update the user can make an informed decision about the proposed changes to boot options.

This does not eliminate the presence of magic comments or ensure that changes to this file by the user can be reliably merged, however it does ensure that local changes will not be silently overwritten.


UI Changes

This change introduces a new debconf question. This will not be displayed on systems with the default configuration, but must be shown to users when upgrading kernels if they have modified their menu.lst outside the constraints of the existing auto-update support.

Code Changes

  • update ucf to support specifying an alternate debconf template to use for the user prompt.
  • modify update-grub to store the autogenerated portion of the boot config with ucf, so that local changes can be detected and handled by prompting the user to resolve conflicts.
  • once the conflict is resolved, /boot/grub/menu.lst is updated with the result.
  • two passes will be required, first to verify whether the magic comments have changed relative to the previous invocation and incorporate any changes if so, and second to update the list of kernels presently available.


This specification imposes no migration requirements on the user.

Test/Demo Plan

Because this spec affects the behavior on upgrades and relies on detecting local admin changes, several distinct test paths are required to ensure complete coverage of this new feature.


  • test: install Ubuntu 7.10. leave /boot/grub/menu.lst unmodified. upgrade to hardy using update-manager -d.

  • expected result: /boot/grub/menu.lst is upgraded to include the entries for the new hardy kernel, with no debconf prompting.

Future Work

  • The /boot/grub/menu.lst file will still contain functional comments, whose contents will be duplicated multiple times in the bootloader config. A future version of update-grub may attempt to heuristically detect these from the existing boot stanzas, for example:
    • Hand-edited kernel options should be intelligently copied to the configuration for newly-installed kernels.
  • This change does not provide any hooks for external packages, such as apparmor or selinux, which may need to update the kernel boot-time options. This may be implemented separately in update-grub.


I can't really understand why to use update-grub at all. It's crap and the first thing I disable (in /etc/kernel-img.conf) after installing a new Ubuntu machine.

  • What use cases does using update-grub solve that the old-days method of using /vmlinuz and /vmlinuz.old symlinks to refer to the current and old kernel does not? (unless having 12 old kernels listed in your menu.lst counts as a use-case:-))
  • If a tool to update menu.lst is really needed (it is?), why not a simple script which update it in place, without all those crappy comments-which-actually-are-directives?
  • IMHO update-grub is the cause of the problems the spec tries to face, not their solution.


We want to make minimal changes to fix the worst problems in Ubuntu 8.04. A more complete re-engineering does make sense at some point in the future (perhaps in conjunction with grub2), but right now, taking the whole system out back and shaking it down is not on the table. --ColinWatson

I have added a comment to the [ referenced bug (#103297)]. There seems to be some confusion arising when the default kernel is changed as a result of the number of stanzas in the "AUTOMAGIC" section changing that this specification does not seem to address. I don't know how the savedefault command works but it is probably worth considering that too. -- JamesAsccroftLeigh