The first phase of the loader project for illumos has landed. There are
important changes for users of illumos and folks that build
distributions. We'd like to thank Toomas Soome for all of his work on
this project and spearheading it. We'd also like to thank everyone who
has helped review and test these changes! The rest of this covers what's
changed and has an FAQ put together by Toomas.



illumos has a new, default boot loader based on the FreeBSD boot loader.
The new boot loader is packaged as "pkg:/system/boot/loader". For the
initial stage(s) we are also keeping the current GRUB based boot loader
and are providing a mechanism to set GRUB as the default boot loader to
support deferred switch to the new boot loader. illumos-gate however, is
defaulting to the new loader, to make sure the new features and
development is possible for developers and early adopters.


Why are we changing boot loaders?

The current boot loader used by illumos, grub-0.97, while providing
basic features to support disk and network based boot support, has
proven to be hard to extend to implement support for new features or
even to fix known issues. Probably the most well-known issue is the lack
of memory management, which is the most limiting factor, setting limits
on implementing new features. In addition, this transition provides the
starting point for UEFI booting, booting from RAID-Z, and more.

How do I enable the new boot loader?

The actual switch to use the new loader is a two step process. The first
step is to update the system with updated components, on an IPS/BE based
system it means the new updated BE will be created by package update,
and the system needs to be rebooted to make the new BE active. After the
boot, updated components are available, but grub is still the currently
installed boot loader. For the second step, the loader boot programs
shoud be installed on disk, and a boot environment menu file should be
created. This can be done by using the beadm create/beadm activate
commands, as beadm create or beadm activate will also create the loader
menu.lst file, and beadm activate also updates the boot programs on
disk(s). An alternate way is to use bootadm install-bootloader or
directly use the installboot command, however, the installboot command
will not create the boot environment menu.

Switching the boot loader prevents automatic boot support for older grub
based boot environments as older boot environments do not have the new
loader configuration files. However, it is still possible to load and
boot such boot environments manually, by using loader commands to load
and boot the kernel:

ok load /platform/i86pc/kernel/amd64/unix
ok load -t rootfs /platform/i86pc/amd64/boot_archive
ok boot

If the BE list was created, the BE can be switched in loader BE menu, or
by using beadm command from the loader ok prompt. If the BE list was not
created, the operator needs to detect the correct zfs dataset name, for
example by using from loader ok prompt:
    ok lszfs rpool/ROOT

And then set the variable currdev:
    ok set currdev=zfs:rpool/ROOT/openindiana:

And continue with loading and booting the kernel.

How do I use the new loader?

Probably the most common use case is to accept default setup and either
wait the default timeout (10 seconds) for automatic boot or to press
enter to bypass the timeout. The default user interface for the new
loader is presented as a text based menu, allowing you to boot, select
kernel options or boot environment. Pressing Enter from any menu will
boot, backspace from options or BE menu will return to main menu and ESC
from main menu will bring up a loader CLI prompt.

The most important loader command list is available by entering ? at the
ok prompt, the rest is visible by the command "words" (this is the word
to see the forth dictionary).

The loader will start its work by interpreting the /boot/loader.rc
script. The actual system configuration is read in the following order
and files:







The *.conf files are mostly used to set environment variables, and each
following entry can override the values set in previous files(s). The
kernel boot arguments can be listed in the variable "boot-args".
The loader supports dual (or mirrored) console by:
    ok set console=text,ttya

If set as above, the loader is accessible from both vga console and
first serial port. If the variable "os_console" is not set, the first
device from the variable "console" is passed to the kernel as the
console device.

If manual boot from ok prompt is performed, any switches passed to
"boot" command will override the values from environment variables.

To support a chain loader in the menu, the variable "chain_disk" can be
set to the name of the device for chain loading. A list of the devices
is available via the lsdev loader command.

What exactly changed with this first phase?

The related changes in the first phase affect the following components
in the system:

    The loader sources are added into the "usr/src/boot" directory tree.

    As loader is using the ficl scripting engine as the interpreter, we
are also building the ficl-sys user space program to ease the test and
development; the ficl source is added into "usr/src/common/ficl" in the

    To support loader boot program installation to disk, the installboot
utility is added for x86 platform.

    To support installboot command, libbe is updated accordingly.

    To support viewing and limited management of loader configuration,
the bootadm command is updated accordingly.

    To support loader and fast reboot feature, the halt, svc.startd, and
eeprom commands are updated accordingly.

    To reflect the switch from grub to loader, the manual pages
beadm(1M), bootadm(1M), and boot(1M) are updated accordingly.

What do I need to do to keep using GRUB?

To keep grub as the default boot loader, the file "/etc/default/be" must
be created, with following line in it:

We are not providing this file in illumos-gate, it should be created and
provided by distribution maintainer(s). The intention is to provide a
temporary mechanism to delay the switch, while making it possible still
to track other updates. Eventually, this override mechanism will be
removed along with grub itself.

What's happening to GRUB?

GRUB will be provided in illumos for some time to give distributions and
users some time to change and transition. Eventually, GRUB will be
removed. We hope to complete this transition within a year, if not sooner.

I'm a distributor, what should I do next?

As a distributor, you should begin evaluating the new boot loader. While
that's going on, you may want to provide the /etc/default/be file. We'd
also suggest looking at any customizations you may want to provide to
the menu interface, whether customizing the menu options or coming up
with a new interface altogether.

I'm a user of illumos, what should I do next?

If you're using a distribution, you'll want to check with the
maintainers of it to figure out their plan. If you're updating illumos
on your own, outside of any given distribution, you should consider
adopting the new boot loader as soon as possible.

Does this help with booting UEFI systems?

While UEFI boot isn't included in this change, this sets the groundwork
for booting via UEFI.

This sounds interesting, how can I get involved?

If you're interested in working on this project reach out in #illumos on
Freenode or talk to Toomas Soome <>.