Configuring Grub Guests

vm-bhyve has built in support for the grub2-bhyve software, which is capable of booting most guests that can be booted by GRUB2. This page describes the various configuration options that can be placed in the guest config file to control grub2-bhyve, and the effect they have.

In order for a guest to use the grub2-bhyve loader, you need to set loader="grub" in the guest configuration file.

The grub loader is run on the guest console, so while the guest is in the Bootloader state, you can access it using the standard vm console guest command. If you start a guest in foreground or interactive (tmux only) mode, you will be placed directly in the grub loader as soon as the guest starts.

No configuration

If you do not specify any grub configuration at all, grub2-bhyve will look for a /boot/grub/grub.cfg GRUB2 file in the guest on hd0, partition 1. If this file exists it will be processed, which in most cases means you will be shown a boot menu with a choice of options.

If no GRUB2 configuration file is found, grub2-bhyve will just drop to the grub> cli.

grub.cfg GRUB2 config file in the guest, non standard location.

If your guest has a GRUB2 configuration file, but it is not in the standard location looked in by grub2-bhyve, you can specify the location using configuration options in the guest. These options are grub_run_dir and grub_run_file.

For example, CentOS 7 seems to use /grub2/grub.cfg. Because the filename is still the same we don't need to change that, but we need to tell grub2-bhyve the new directory to look in:

grub_run_dir="/grub2"

If for example, your guest operating system calls the file /grub2/grub2.conf, you could specify the following:

grub_run_dir="/grub2"
grub_run_file="grub2.conf"

grub.cfg configuration on a different partition

By default vm-bhyve specifies hd0,1 as the root for the guest disk partition. If your boot partition is not 1, an alternative partition can be specified in the configuration file.

grub_run_partition="2"

With this configuration, grub2-bhyve will look in (hd0,2)/boot/grub/grub.cfg for the grub configuration file. The partition also affects custom commands, so let's say you specify the following configuration for example:

grub_run_partition="2"
grub_run0="linux /vmlinuz" 

This will effectively perform the same as running linux (hd0,2)/vmlinuz from the grub> cli.

No GRUB2 in the guest, custom boot commands

As mentioned above, if the guest has no GRUB2 configuration file, when the guest starts grub2-bhyve will just fall back to the grub> cli. At this point you can connect to the guest and enter the relevant commands to boot it. For example to boot NetBSD, you could access the grub cli and enter the following:

grub> knetbsd -h -r ld0a /netbsd
grub> boot

Of course, running this every time you start or restart the guest is not ideal. However, you can specify the needed commands in the guest configuration file (boot is not required):

grub_run0="knetbsd -h -r ld0a /netbsd"

If more than one command is needed, add additional lines and change run0 to run1, then run2, etc. If any boot commands are specified in this way, vm-bhyve will create a custom grub.cfg file. On booting the guest, a custom grub menu is displayed containing a single guestname (bhyve run) option. This option is then chosen by default after 3 seconds. (The 3 second timeout can be changed using the loader_timeout="X" guest configuration option)

For most linux guests it's preferable to install GRUB2 in the guest if possible as it allows the guest to manage the configuration file. Sometimes a kernel upgrade can require changes to the boot commands, and if the commands have been manually entered into the guest config file, it will not boot until they are manually updated.

Installer commands

As normal, grub2-bhyve will look in /boot/grub/grub.cfg on the cd for a grub configuration file. If it can't find one it will drop to the grub> cli. We do not provide configuration options to tell grub2-bhyve to look in other locations, but we do provide the facility to specify custom boot commands. As an example, these are the commands from the CentOS 6 sample template that successfully boot the ISO installer

grub_install0="linux /isolinux/vmlinuz"
grub_install1="initrd /isolinux/initrd.img"