|
Introduction
BURG stands for Brand-new Universal loadeR from GRUB. It's based on GRUB, and add features like new object format and configurable menu system. This page shows its usage.
Install using binary package
- For Ubuntu 10.04 and 10.10 users, add the following PPA :
sudo add-apt-repository ppa:bean123ch/burg
- For Ubuntu 11.04 users, add the following PPA :
sudo add-apt-repository ppa:n-muench/burg
- Then use the following command to download and install the loader, themes and emulator:
sudo apt-get update && sudo apt-get install burg
- During the installation, it should ask you to write the new boot loader to MBR. If you skip that step, you can later use the following command to update MBR of hd0:
sudo burg-install "(hd0)"
or ( FIXME ??? burg-pc package does not exist ! )
sudo dpkg-reconfigure burg-pc
Install using source code
Build from scratch
To compile burg project, you need to have the following software in your OS:
gcc gcc-multilib (to compile x86_64 targets from i386 os, or vice verse) bison autoconf automake gettext GNU make ruby python
Debian/Ubuntu
Use the following command to install them:
sudo apt-get install gcc gcc-multilib bison autoconf automake gettext make ruby python
OSX
You need to install Xcode. I've successfully compiled burg from 10.4 Tiger with Xcode 2.5, 10.5 Leopard with Xcode 3.0, and 10.6 Snow Leopard with Xcode 3.2.
The latest version of BURG depends on gettext, which is not shipped with OS. You need to install the one from macport. You also need to install autoconf and automake, as the ones in Xcode can't find gettext macro properly.
For 10.4 Tiger, bison is too old, you need to install it from macport.
Macport uses prefix /opt/local, you need to pass the following parameter in configure:
./configure CFLAGS="-I/opt/local/include" LDFLAGS="-L/opt/local/lib"
Windows
You need to install mingw32 or cygwin. ruby is not included in mingw32 so you need to install it separately.
Get Source Code
You need bazaar to download source from launchpad. Initial import:
bzr branch lp:burg
Later, you can use the following command to update to latest version from the work directory:
bzr pull
After fetching the code, you should run autogen.sh to regenerate the makefiles:
./autogen.sh
Build and install (pc)
Use the following commands to compile burg (assumes you're in the work directory):
mkdir bin_pc cd bin_pc ../configure --with-platform=pc --prefix=${HOME}/burg_pc make make install
In this example, I use sub directory bin_pc to store compiled files for pc platform, this avoids generating a lot of files in the source directory, and you can have different build directories for different platform.
The prefix is used to specify a target prefix when running make install. I suggest not to use default location otherwise it could overwrite the grub2 package.
Note: new version of BURG uses gettext, and grub-mkconfig expects to find gettext.sh in the bin directory, so you need to make a symbol link:
cd ${HOME}/burg_pc/bin ln -s /usr/bin/gettext.sh gettext.sh
Also, with the above prefix, the config file is at ${HOME}/burg_pc/etc/default/burg.
After the above steps, burg is installed to ${HOME}/burg_pc, you need to install it to MBR in order to use it as boot loader.
WARNING: the following step only works in Linux, don't try it in OSX or Windows.
cd ${HOME}/burg_pc/sbin sudo ./burg-mkconfig -o /boot/burg/burg.cfg sudo ./burg-install "(hd0)"
Build and install (efi)
The build process is quite similar to pc, just change --with-platform parameter. You also need to add --target if compile 64-bit target from 32-bit OS, or vice verse:
32-bit EFI
mkdir bin_efi32 cd bin_efi32 ../configure --with-platform=efi --target=i386 --prefix=${HOME}/burg_efi32 make make install
64-bit EFI
mkdir bin_efi64 cd bin_efi64 ../configure --with-platform=efi --target=x86_64 --prefix=${HOME}/burg_efi64 make make install
You need to generate an EFI image using burg-mkimage, for example:
cd ${HOME}/burg_efi64/bin ./burg-mkimage -o grub64.efi minicmd part_gpt part_msdos part_apple fat ext2 hfsplus hfs ntfs reiserfs xfs iso9660 udf ls search loopback linux chain reboot halt appleldr help configfile hexdump loadbios memrw fixvideo crc sh video efi_fb gfxterm font png loadcfg normal coreui gfxrgn txtrgn nmenu emenu
Copy grub64.efi to a location where it can be found by rEFIt. You also need to create a config file burg.cfg in the same directory as grub64.efi, for example:
menuentry "Boot OSX" { search -s -f /usr/standalone/i386/boot.efi chainloader /usr/standalone/i386/boot.efi } menuentry "Boot MBR" { appleloader HD } menuentry "Boot CD" { appleloader CD }
New Menu System
Usage
To enable the new menu system, you can download the themes from:
http://groups.google.com/group/burg-devel
There are currently three themes in the files section:
theme_default.tar.gz Default themes, containing theme minimum, proto, ubuntu and winter
proto:
ubuntu:
winter:
theme_sora.tar.gz Sora themes created by Evan Gillies, containing theme sora, sora/clean and sora/extended.
theme_chiva.tar.gz Chiva theme created by snolice in ubuntu cn forum, containing theme chiva.
Extract them to burg directory:
cd /boot/burg sudo tar -xzf ~/theme_default.tar.gz sudo tar -xzf ~/theme_sora.tar.gz sudo tar -xzf ~/theme_chiva.tar.gz
Then edit burg config file, which should be /etc/default/burg if you are using the ubuntu ppa package. GRUB_THEME select the theme, and GRUB_GFXMODE sets screen resolution, for example:
GRUB_THEME=ubuntu GRUB_GFXMODE=640x480
Finally, you need to generate burg.cfg with (ubuntu includes command update-burg which does exactly the same thing)
sudo burg-mkconfig -o /boot/burg/burg.cfg
If you decide to change the theme later, you need to rerun update-burg to update burg.cfg.
The burg.cfg for EFI mode is normally construct by hand. To enable themes, just need to append these lines at the end of burg.cfg:
set gfxmode="0x0" set gfxfont="Unifont Regular 16" load_config /boot/burg/ubuntu/theme.txt menu_viewer.ext
The theme file defines the following hot keys:
- e - edit the current command
- t - edit the current title
- c - open a terminal window
- 2 - open two terminal window
- F5 - mapped to ctrl-x, used to finish edit and save the result
- F6 - move to next anchor, normally have the same function as TAB, but it is useful in cases where TAB is used for other function (such as term),
- F8 - toggle between text and graphic mode
- F9 - shutdown
- F10 - reboot
- ESC - return from popup window
The following sections describe the format of theme file in details.
Basic Structure
The format of theme file is quite straightforward, {} is used to start a child node, and = is used to set properties, for example:
screen { panel { extend = 1 valign = center halign = center panel { class = frame id = __menu__ } } panel { id = __timeout__ attach_bottom = 1 width = 60% halign = center height = 1 progressbar { width = 100% height = 100% color = "red:brown" } } } mapkey { f5 = ctrl-x }
The topmost element in a theme file defines a section, each section have a specific function. For example, screen section is used to define screen layout, while mapkey section defines key mappings.
There are two command to read theme file, load_config and merge_config:
load_config /boot/burg/default.txt
The difference between load_config and merge_config is that if a section already exists, merge_config merges the new section into existing one, while load_config replaces it.
Data Representation
The theme file is supposed to work in both text and graphic mode, so there can be multiple components packed inside a single property.
Size
All properties that specify size uses the following representation:
10
10 character size in text and graphic mode. In graphic mode, the size is calculated using system default font, which is set using gfxfont variable. Please note that width=1 and height=1 is not the same size in pixels.
10%
The size is 10 percentage of parent widget, in both text and graphic mode.
10/1
10 pixels in graphic mode, and 1 character in text mode. Either component can use the percentage notion as well, such as:
10%/20%
10 percent in graphic mode, 20 percent in text mode.
Color
red
Red, in both text and graphic mode.
The recognized color named is as follows:
- black, blue, green, cyan, red, magenta, brown, light-gray - can be used as foreground or background color in text mode.
- dark-gray, light-blue, light-green, light-cyan, light-red, light-magenta, yellow, white - can only be used as foreground in text mode.
red/blue
Foreground color is red, background color is blue, works in both text and graphic mode.
#808080/red/blue
Use #808080 in graphic mode, foreground color red, background color blue in text mode.
Widgets become selectable if there is associated command. In this case, you may want to use different color when the widget is in selected state, this can be achieved by joining two color together with ":":
cyan/blue:light-gray/blue
When the widget is selected, foreground color is light-gray, otherwise it's cyan. Background color is blue in both situation.
Image
,,blue,#0
Draws a blue rectangle box, in both text and graphic mode.
,,blue,c
Draws a blue rectangle box using fill character 'c', in both text and graphic mode.
,,blue,#0x250F
Draws a blue rectangle box, using unicode glyph 0x250f as fill character, in both text and graphic mode.
/splash.png,,blue,#0
Draws image /splash.png in graphic mode, blue rectangle box in text mode, you can also specify a fill character.
/splash.png,,blue
Draws image /splash.png in graphic mode, nothing in text mode.
/splash.png
Same as above, but uses default scaling method and background color.
none,,blue,#0
Draws blue rectangle box in text mode, nothing in graphic mode.
In the above examples, the second parameter are all empty, it specify the scaling method of images, and can use one of the following value:
- scaling (default) - scale the image to fit the width/height of widget.
- center - draw the image at the center
- tiling - repeat the image until it fills the area.
- minfit - keeps ratio scaling, it ensures the entire image is shown, but it can leave blank at top/bottom or left/right.
- maxfit - keeps ratio scaling, it ensures no blank is left, but the image can be truncated at top/bottom or left/right.
For drawing methods that leaves blanks (center and minfit), it uses the color in third parameter as background.
Just like color, you can joined two image together using ":" to specify different image when the widget is selected.
,,cyan/blue,#0x250F:,,light-gray/blue,#0x2554
Common Properties
Some properties are shared by all widgets. This includes properties used by layout manger, command, anchor and class.
Layout manager
You can place a widget in one of two ways. You can set its location directly, or you can let the layout manager figure it out for you.
For absolute positioning, you can use the following properties:
- attach_top - distance to the top border of parent
- attach_bottom - distance to the bottom border of parent
- attach_left - distance to the left border of parent
- attach_right - distance to the right border of parent
- attach_hcenter - offset from the horizontal central line
- attach_vcenter - offset from the vertical central line
If none of the above properties are set, layout manager would try to calculate the position of widget for you. You can control its placement using these properties:
- extend - if set to 1, extend the widget in the direction of parent.
- valign - can be top, center, bottom or extend (default).
- halign - can be left, center, right or extend (default).
The parent widget uses the following properties to control the placement of children:
- direction - The direction, its value can be top_to_bottom (default), bottom_to_top, left_to_right or right_to_left.
- space - The space left between two children.
You can also set the size of widget with these properties:
- width - width of widget
- height - height of widget
If one of the above properties is not set, layout manager would try to calculate the width/height for you, which is normally the minimum size to contain its children, although it can also be expanded using the extend property mentioned above.
Sometimes you want the layout manager to calculate the size for you, but you don't want the widget to because too large or too small. In this case, you can use the following properties to limit the size of auto calculated widgets:
- min_width - minimum width of widget
- max_width - maximum width of widget
- min_height - minimum height of widget
- max_height - maximum height of widget
Please note that these properties have no effect if the size is set explicitly using width/height property.
Command
The command property associate action for current widget. Once it's set, the widget become selectable, navigation keys like up/down/left/right jumps to the next widget with command property set, and enter key execute the command.
To specify multiple commands to run in this property, use '\n' as separator. For example:
command = "chainloader +1\nboot"
Anchor
Sometime you need to group some widgets together. For example. when navigating inside a menu, you may want to loop back to the last item when using the previous key on the first item. This can be archived by setting anchor to 1 in the parent widget. Key like tab jumps to the next selectable widget in another anchor, so it can be used to switch between different menus.
Class
Many widgets share the same property value. For example, we need to draw a rectangle box in many occasion, such as in menu, sub menu, terminal window, etc. Instead of duplicate the same set of properties many times, we can give it a name using the class property, the real property is set in the class section.
If class property is not set, it would try to locate default properties using widget name.
screen { panel { class = frame } panel { class = frame } } class { frame { top_left = ",,cyan/blue,#0x250F:,,light-gray/blue,#0x2554" top = ",tiling,cyan/blue,#0x2501:,,light-gray/blue,#0x2550" top_right = ",,cyan/blue,#0x2513:,,light-gray/blue,#0x2557" left = ",tiling,cyan/blue,#0x2503:,,light-gray/blue,#0x2551" right = ",tiling,cyan/blue,#0x2503:,,light-gray/blue,#0x2551" bottom_left = ",,cyan/blue,#0x2517:,,light-gray/blue,#0x255A" bottom = ",tiling,cyan/blue,#0x2501:,,light-gray/blue,#0x2550" bottom_right = ",tiling,cyan/blue,#0x251B:,,light-gray/blue,#0x255D" } screen { background = ":,,blue,#0" } }
Widgets
Widget is the basic element to construct the user interface. There are several widgets, each have a set of properties to control its behavior.
panel
Panel is a container for other widgets. You can set the border for panel. There are four set of border properties, from outward to inward:
- padding_size, padding_top, padding_bottom, padding_left, padding_right - This is the most outward layer of empty strip for panel, padding_size set the default value for all four borders, you can overwrite specific size with property like padding_top.
- border_color, border_size, border_top, border_bottom, border_left, border_right - The second layer, consists of solid color.
- top_left, top, top_right, left, right, bottom_left, bottom, bottom_right - The third layer, consist of 8 images.
- margin_size, margin_top, margin_bottom, margin_left, margin_right - The most inward layer, an empty strip to prevent children widgets from getting too closed to borders,
- background - Background image. This includes the space reserved by margin_*.
screen
screen is the topmost widget. It's just like panel, but it doesn't have a external border so it only uses property margin_* and background.
text
Text is a widget to show single line of text. It has the following properties:
- text - The string to show
- gfx_text - The string to show in graphic mode, if it's not set, both text and graphic mode shows the same text.
- color - Text color
- font - Text font
image
Image is a widget to show a single image, Property:
- image - The image to show
edit
Edit is a widget to show a edit box. Properties:
- max_lines - The maximum number of lines to store. max_lines=1 means single line edit. max_lines=0 means unlimited lines. If it's not set, default value 100 is used.
- lines - The number of lines to show in screen. This is used to calculate the height of widget, so don't mix it with height property.
- columns - The number of columns to show in screen. This is used to calculate the width of widget, so don't mix it with width property.
- text - The initial text. You can set multiple lines of using the \n separator.
- color - Text color.
- font - Text font.
In the edit widget, use ctrl-x to save the current edit and returns, ESC to cancel.
term
Terminal emulator, it shares properties with edit widget.
password
Password is a single line edit widget, but unlike edit, it shows * instead of the real input character. It uses properties columns, color and font.
progressbar
This is used to show the process bar before timeout is reached. Property:
- color - The color of progress bar. First component is the color for passed time bar, and second component is for remaining time bar. If there is not second component, only the first bar is visible.
circular_progress
Same as the progressbar, but a circle instead of a bar. Properties:
- tick - the image/colors to use to use for each progress tick around the circle
- background - the image to use as the background of the circle (note, to make the ticks appear outside the background image, there needs to be a transparent border on the background image.)
- num_ticks - the number of ticks to draw around the circle. Between 0 and 100. default: 24
- start_angle - sets the starting location of the ticks. 90 degrees is the top. between 0 and 360. default: 0
- clockwise - set this to 1 to make the ticks rotate clockwise. default: 0 (counter-cockwise)
Template
Template is used to define composite component. For example:
dialog_hello { panel { parameters = "text=text.text" class = frame text {} } }
The property parameters defines the mapping between parameters and internal properties. This template accepts one parameter text, which is mapped to the text property of text widget.
Some template are used internally so they must be defined in the theme file:
- dialog_message - shows a dialog box with single text message. Must accepts text parameter which is the content of the text.
- dialog_password - shows a password input dialog. Must accepts username and password parameter which mapping to the username and password input text.
- template_submenu - Template used to generate sub menus.
- template_menuite - Template used to generate the boot menu items. Must accepts title and class parameter.
Here are the definition of these templates in the default theme file:
dialog_message { panel { parameters = "text=text.text" class = frame margin_size = 1 margin_bottom = 0 space = 1 attach_hcenter = 0 attach_vcenter = 0 text {} panel { class = frame command = true halign = center margin_left = 1 margin_right = 1 text { text = OK } } } } dialog_password { panel { parameters = "username=__user__.text:password=__pass__.text" class = frame margin_size = 1 margin_bottom = 0 attach_hcenter = 0 attach_vcenter = 0 panel { direction = left_to_right space = 1 text { extend = 1 valign = center text = Username } panel { class = frame margin_left = 1 margin_right = 1 edit { id = __user__ max_lines = 1 } } } panel { direction = left_to_right space = 1 text { extend = 1 valign = center text = Password } panel { class = frame margin_left = 1 margin_right = 1 password { id = __pass__ } } } panel { class = frame command = true halign = center margin_left = 1 margin_right = 1 text { text = OK } } } } template_submenu { panel { class = frame } } template_menuitem { panel { parameters = "class=image.class:title=text.text" class = select direction = left_to_right image {} text { valign = center } } }
This theme pop up the sub menu alongside parent, if you prefer to show the sub menu full screen, you can replace template_submenu with this:
template_submenu { panel { width = 100% height = 100% panel { id = __child__ class = frame valign = center halign = center extend = 1 } } }
Here, the widget with id child is the place to insert auto generated (using template_menuitem) sub menu items.
You can control the placement of popup submenu using the popup property, for example:
screen { panel { id = __menu__ popup = left } } template_submenu { panel { class = frame popup = right } }
The values can be:
- left, right, top, bottom - the position of popup submenu related to the current selected widget.
- abs - Absolute position, submenu starts at (0, 0).
The popup is not set, menu system tries to decide popup position automatically,
With template, the screen section is very simple:
screen { panel { extend = 1 valign = center halign = center panel { class = frame id = __menu__ } } panel { id = __timeout__ attach_bottom = 1 width = 60% halign = center height = 1 progressbar { width = 100% height = 100% color = "red:brown" } } }
The widget with id menu is the place to insert auto generated top level menu items defined with menuentry statement in grub.cfg. The widget with id timeout is used for timeout control. When auto booting is paused by key press, widget with id timeout and all its children would be hidden.
You can also use command menu_popup to create a dialog box based on templates. For example, to create a hello world message box, we can use the dialog_message template:
menu_popup dialog_message "text=Hello, World"
Command menu_edit is quite similar to menu_popup, but it uses two direction parameter assignment, it's used to implement the command edit box. First, we define the template in theme file:
dialog_edit { panel { parameters = "text=edit.text" class = frame width = 80% attach_hcenter = 0 attach_vcenter = 0 edit { lines = 10 } } }
Then uses this command to start the dialog box:
menu_edit dialog_edit text=command
In entry, the text parameter of the dialog box is set to the command parameter of current widget. After edit is done, we reverse the order and update the command parameter to the new text.
User interaction
With the new ppa package update (2010.06.07) there is a new cool command named menu_read. it's used to enter a property from a dialog window and assign it to a variable. This template can be used for user interaction, for example, add this dialog template to theme file
dialog_input { panel { parameters = "old_value=__old__.text:new_value=__new__.text" class = frame margin_size = 1 margin_bottom = 0 attach_hcenter = 0 attach_vcenter = 0 panel { direction = left_to_right space = 1 text { extend = 1 valign = center text = "Old value" } text { id = __old__ } } panel { direction = left_to_right space = 1 text { extend = 1 valign = center text = "New value" } panel { class = frame margin_left = 1 margin_right = 1 edit { id = __new__ max_lines = 1 } } } panel { class = frame command = "menu_read new_value AA" halign = center margin_left = 1 margin_right = 1 text { text = OK } } } }
The template above can be displayed using:
menu_popup dialog_input old_value=${AA}
The "Old value" field display the value of variable AA, and the value of "New value" edit box will be assigned to AA when you click "OK".
Define hot keys
You can use keymap section to map some key to another. This is useful in platform like EFI where keys like ctrl can't be input.
onkey section associate grub command to keys. If a key is already handled by the current widget, the command defined in onkey section is ignored. For example, inside the terminal window, c is used as input character, so the command defined in onkey is ignored.
onkey { e = "*menu_edit dialog_edit text=command" t = "if menu_edit dialog_line text=title; then menu_refresh; fi" c = "*menu_popup term_window" 2 = "*menu_popup two_term" f6 = ui_next_anchor f8 = menu_toggle_mode f9 = halt f10 = reboot } mapkey { f5 = ctrl-x }
The * at the beginning of command meaning this command is password protected, this will be explained in the next section.
Password
To enable password protection, you need to add these commands at the beginning of grub.cfg:
set superusers=admin password --md5 admin '$1$A1tpOB3$bTHEMeIVvBbQsLZIWmJp/.' password user1 user1
The superusers variable set super users. password command set password for individual user. With --md5 option, the password should be md5 password, otherwise it's plain text.
To generate md5 password, uses grub-mkpasswd command:
grub-mkpasswd admin
Output:
$1$A1tpOB3$bTHEMeIVvBbQsLZIWmJp/.
You can also uses openssl to generate it:
openssl passwd -1 -salt 1234567 admin
Output:
$1$1234567$ergpnZu0mLdD77Dbmwjpb1
To protect certain boot items, add --users option in menuentry statement:
menuentry Item1 --users user1 { true }
Only user1 and super users can access this boot item.
In hot key definition, you can add * at the beginning of command so that only super users can access it.
Save default
To enable save default, you first need to generate a environment file using grub-editenv:
sudo grub-editenv /boot/grub/grubenv create
Default location for environment file is grubenv in the grub directory, although you can overwrite it with envfile variable. Command load_env read the environment file from disk.
To enable save default for all items, you can set savedefault=1 in grub.cfg, to skip some item, adds --nosave option in menuentry statement. If you only want to save a few items, then you can skip savedefault=1, but adds --save option in items you want to save. For example:
set envfile=/boot/grub/grubenv set savedefault=1 load_env menuentry Item1 --nosave { true } menuentry Item2 --save { true }
You also set default item using config file, for example, to boot the first item, add this line to /etc/default/grub:
GRUB_DEFAULT=0
To boot the saved item from last boot:
GRUB_DEFAULT=saved
Don't forget to use grub-mkconfig/update-grub to update the real grub.cfg.
Timeout
You can use timeout variable to enable auto boot if no key is pressed in N seconds:
set timeout=5
If timeout is set to 0, boot immediately, although you can stop it by pressing any key at startup. In the case of timeout=0, the menu is not drawn unless auto boot process is halt.
Timeout can also be set in config file using variable GRUB_TIMEOUT.
Menu Icon
To add icons to boot items, uses --class option:
menuentry Item1 --class image_ubuntu { true }
Then in theme file, define the image_ubuntu class:
class { image_ubuntu { image = "${prefix}/icons/ubuntu.png" } }
Default Menu
You can append a default menu following the items defined with menuentry. Default menu is defined in theme file using menu section:
menu { Tools { class = image_dir users = user save = 0 "Toggle Mode" { class = image_tools command = menu_toggle_mode } "Terminal" { class = image_term command = "menu_popup term_window" } "Two Term" { class = image_term command = "menu_popup two_term" } "About" { class = image_about command = "menu_popup dialog_message \"text=This is GNU GRUB\"" } } Shutdown { class = image_shutdown command = "halt" } Restart { class = image_restart command = "reboot" } }
Here, class property corresponds to the --class option in menuentry, users corresponds to --users, save=1/save=0 corresponds to --save and --nosave.
PXE Dynamic Configuration
BURG adds a new command pxecfg, which can be used to execute certain command based on current IP/MAC address.
First, write a pxe config file, whose format is quite similar to menu theme.
ip { 192 { 168.2 { command = "echo ip 192.168.2.*" } 169 { command = "echo ip 192.169.*.*" } command = "echo ip 192.*.*.*" } } mac { 00-0c-29-1a { command = "echo mac 00-0c-29-1a-*-*" } command = "echo mac *-*-*-*-*-*" }
Use this in grub.cfg to load the config file:
pxecfg /config.txt
See Also
Troubleshooting
Q: burg won't find a grub.cfg.
A: newer versions use burg.cfg
internal Links
external Links
Development: http://code.google.com/p/burg/
Ubuntu: https://launchpad.net/burg
Forum: http://www.burgloader.com/bbs
Mailing list: http://groups.google.com/group/burg-devel
Screenshots: http://code.google.com/p/burg/wiki/Screenshots