Revision 8 as of 2007-11-20 12:44:46

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

It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during CD testing, and to show off after release.

This need not be added or completed until the specification is nearing beta.

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.