trusty-boot-key

To simplify development and docs we've removed everything related to ancient BIOS, MBR, and <= 32-bit architectures. Yes—it's been about twenty years since we had one of those in the house. There's still a late 2013 MBP running acceptably here, with UEFI and 64-bit support, currently pushing thirteen years old.

If you're a vintage computing enthusiast on a souped-up 486/DX9, fine—this project isn't for you. Otherwise, there are likely free computers offered thru your local craigstlist meeting the ~2010 specs listed above, sometimes even left on a sidewalk or trash-bins in larger cities. If you're willing to spend upwards of perhaps… ~$250? One could probably find something more formidable from the last decade.

ARM, R-V?

While it's possible we could support ARM64 or even RISC-V systems in the future, there are none of those laying around handy at the moment. Oh wait, there is an RPi 4 in a drawer nearby… Unsure how to get started on that however, and there's still a lot to do.

Operating Systems

Everything Linux seems to work, although on older images you may have to write some kernel parameters into a support file. We've done that work for loopback.cfg-compatibles and a few very popular other distros, but will need your help for the more obscure ones. See contributing below.

Windows, BSD?

These aren't able to work from a .iso loopback device. Some folks say that creating a partition and unpacking the .iso there works.

Update: Tried Windows 10 and the installer starts up, although with an error. See the customization section later on.

╭───────┬──────────────────╮
│  ESP  │  Data Zone --->  │
╰───────┴──────────────────╯

What you see above is a disk diagram, cut in two (or more) parts. (Well, a unit of storage perhaps—they don't look like frisbees internally any longer.)

We can divide a storage device into sections according to function, each optimized for its needs. In this situation each section is called a "partition," and nearly always contains a "file-system" to catalog the files. These different filesystems have tradeoffs of their own, typically relating to both functionality and compatibility.

The first partition above is the "E.S.P.," a recursive acronym that expands to the "E.F.I" System Partition standard. It uses the venerable and simplistic FAT filesystem, that just about any operating system since the 80s can read. This is a standard for boot partitions that gives much more flexibility than the old-fashioned boot sector.

We'll help you create the partitions and install "GRUB" up in there. That is GNU GRUB, a slender operating system masquerading as a boot loader. Interesting in that we thought we done with it, moving several desktops to systemd-boot in recent years. UEFI machines generally don't need all that functionality any more, it comes standard. But the flexibility of ol' grub here is of great benefit to mounting and running .iso files for a "trusty boot key."

"High-way to the data zone…"

The second partition should be much larger and where you're gonna drop those phat eye-soes or "boot images", in other words. These might load a number of operating systems temporarily as well as for permanent installation. Supported binaries (think memtest86) and .efi files should work as well.

Currently, we are using the ext4 filesystem for the data partition. This is a tough one to decide on, as each of the main choices has significant drawbacks:

• FAT32 - most compatible, but no files larger than 4GB, ruling out many .iso files.

• Exfat - very compatible, though the Ubuntu family doesn't support booting from it.

• UDF - widely compatible, though obscure and often forgotten. The Bluehat family doesn't support booting from it. No Apple support inside a partition.

• Ext4 - compatible with all Linux (except debian netinst), permissions a minor annoyance on a removable drive. Not typically supported elsewhere.

It seemed that exfat was the best choice at first, but as mentioned the Ubuntu family doesn't support booting from it. Ext4 is a good choice for a Linux-centric user, but you may want to change it back to exfat if you'll be using it often with Windows machines or Macs. (See the "customization" section later on for instructions.)

(There is a third optional partition however, so one could pick their two favorites if necessary.)

There still could be an issue or two lurking however—the code has been changing—no warranty expressed or implied. Recommend starting with a throwaway key, and reading everything the installer below tells you closely.

Get TBK:

Near the top right of the page ⤴, you'll see a git repo URL to clone from:

    git clone https://codeberg.org/aol/trusty-boot-key.git
    # or
    git clone ssh://git@codeberg.org/aol/trusty-boot-key.git

No git? Well, next to that is a link with a [⋯] icon, click on that to download an archive from the menu, and then unpack it.

The scripts inside currently need these packages to run, it's best to install them beforehand:

• Adwaita mono - fedora:adwaita-mono-fonts, arch:adwaita-fonts, debian: not-available - uses DejaVu mono instead.
• dosfstools
• grub2 grub2-efi-x64-modules - arch:grub
• parted
• udevadm - from systemd so probably have it
• udisks2
• optionally exfatprogs ntfsprogs, etc for other filesystems.

It's also a good idea to put yourself in the disks group, so you don't have to run sudo for the update script:

    sudo usermod -aG disk $USER
    # You can log out and back in to reload groups or run:
    exec su -l $USER

    /dev/sda    # whole device
    /dev/sda1   # first part

To install to the drive itself:

Beware! Setup-drive.sh will carve up and format your disk.

Note: The X below represents a removable drive, likely a or b, but potentially a later letter. Do not give a partition number at the end—this one wants the whole device:

    cd ./trusty-boot-key  # this repo, ¡importante!

    ./setup-drive.sh DEVICE  # aka /dev/sdX  - no number

Then follow instructions, which is basically to hit the "y" key and hit ENTER several times.

If successful, the setup-drive script will do the full grub-update steps mentioned below as well. So if you completed setup, no need to do it again below. (Good idea to read however.)

Install Optional Tools:

What are tools? Currently they consist of an open-source UEFI Shell, as well as the MemTest86plus utility.

Would you like these handy on your TBK? They are already installed inside many .iso's, so no big deal. But if you'd like them up front and center, run this command:

    ./get-tools.sh  # -e, -m, or --all

The script above will attempt to download the tools, unpack them if necessary, and copy the binaries to your TBK on the first partition at Trusty-Boot:/grub-tbk/tools. If successful, they'll also be added to the Utilities… entry available from the main menu.

(This tool is simpler than the update-tbk.sh script (detailed below) currently, and expects the ESP to be mounted already at its typical automount location with the configured volume/label name.)

Additionally, if you'd rather grab these yourself, they can be obtained manually and dropped into the Data partition under Trusty-Zone:/os-images, where they'll be listed in the menu automatically.

An update will be needed if you've done a git pull for the latest version of TBK, updated the config file, or you've written some custom "grub script" yourself.

Note1: This is for updating the main menus or defaults. The "OS Images" menu list will look for boot images on the second partition every time, live. No need to "update config" just for that!

Note2: This one wants to update the ESP, so do give a partition number at the end—which should be 1. X will be the same lower letter of the alphabet used above:

    ./update-tbk.sh DEVICE_NUM  # aka /dev/sdX1 - include part. num 1

On rarer occasions you may want to rebuild and upgrade grub itself or the font it uses. Adding a grub module as a built-in requires this, and external module additions are conveniently installed as well:

    ./update-tbk.sh -g DEVICE_NUM  # aka /dev/sdaN

Secure boot—not supported yet! Not sure that we will as it's a pain in the rear. Can you help?

Sorting the OS Images Menu

Despite excessive functionality in other areas, GRUB is only able to sort menu entries though some very hacked-up grub script, and just barely. We were able to implement a bubble sort, though there is no list or array type, so item-swap is done through string operations. Very low performance! Not been a problem so far with a dozen images or so. Twenty might be doable on a fast machine? Dunno, we'll see how that plays out. For this reason, sort can be turned off for now, see below.

If one moves the files off the drive and then returns them the operation typically will be performed in alphabetical order, meaning they'll be sorted on disk. If not, try rsync. This should speed up the sorting performance as well. Better yet, copy them manually in the order of use. e.g. most used image copied first, second second etc. Then turn off sorting.

Customization

You can easily place custom entries into the menu by placing grub-script into a file at the following location:

    $prefix/custom.cfg

Prefix is grub-speak for the main grub folder, currently at Trusty-Boot:/grub-tbk. In this case, at the root of the ESP partition of your removable drive. The first and smaller partition.

If this file is found, the contents inside will be evaluated. Make sure it is syntactically correct or it will break things afterward. Starting very simply and building from there is the best way.
grub-script-check custom.cfg is your friend.

_config.sh

One can also edit the _config.sh file in the repo when ready to get serious with customization. The default localization for example, (currently limited to a few western languages due to font restrictions).

You can also add additional grub modules, change labels and the theme, the size of the first partition, and even the filesystem of the second (or third!) partition, among other things.

Themes

There are three levels of quality. A VGA-style text-mode interface is available in a pinch with the Escape key pressed at early boot time. Called "" (empty-string, a.k.a. none) in _config.sh.

We're using the 'simple' theme by default, which has HD resolution, a unicode font, and some color.

The graphical version includes a lightly-modified Slaze theme by adi1090x/uGRUB, Galaxy, and Stones. Choose in _config.sh and remember to run update with the -g option once to build additional grub graphical theme modules and install them:

./update-tbk.sh -g /dev/sdX1

Themes then need to be copied to ESP:/grub-tbk/themes/$THEME_NAME. The theme file currently must be named theme.txt. Then write the folder name into _config.sh under GRUB_THEME=.

Help and Utils menus

There's a help menu that has a few useful entries for someone not that familiar with GRUB or PC technology in general, but is interested in learning.

Support modules, such as a serial console or additional filesystem support can be loaded as well, all from the Utilities and Drivers menu.

By default this starts up in graphics mode at 1920x1080 resolution with and a medium-large font. Which should be the bare minimum these days. However, maybe you're in a pinch, hacking on a machine in the closet with a relic of a monitor and that's not gonna work.

Well, at startup up you can hold down the shift key to skip the graphics term and use the standard monochrome (GOP? VGA?) console instead. (One sacrifice we make to the ancients.)

Update: that functionality with the keystatus --shift key doesn't seem to work on our UEFI EDK2 machine. So we're using the sleep command instead, and you'll need to hit the Escape key instead, quickly at first boot to bypass graphics mode!

Graphics modes

The videoinfo command might be your friend in this case, it will list supported modes and you can go back down to a fallback resolution with the following incantation:

    set gfxmode="1024x768x32,auto"

Which was a fancy resolution in the early years. ;-) Now that I think of it, staying in the monochrome console probably makes more sense in that case. But, if you've read this far then you've learned how to handle other situations, like if the text is too big, or way too small on your 8k!  Then save it to _config.sh.

Tested

This has been tested installing from:

• Fedora 44
• Arch 26.07
• Ubuntu 26.04 (Adwaita mono not packaged, uses DejaVu instead. Also need to install additional grub locales if desired.)

So far. Doesn't use many fancy features so should run in older versions, but we'll see.

Has been tested with these images, that have loaded successfully:

• .iso files
• .efi files
• memtest86 binaries that use the linux boot protocol.

Windows

Not currently working. It loads but install fails with a "Needs media driver error."

FreeBSD

We understand the process is quite likely similar to the Windows section above, substituting UFS2 or ZFS for NTFS. Haven't yet tried it. Let us know if it works.

Recommended Images

• Arch - Up to date desktop, rolling

• Fedora - Up to date desktop, every 6-month release

• Mint - Long-term support (LTS) desktop, 2-year release

• Tails - Anonymity

• Kali - Forensics, pentesting

• Memtest86 - RAM tester

• UEFI Shell - The shellx64.efi works.

• Mosby - looked interesting.

For memtest you can download the "Binary Files" link, unpack the archive and copy the *_x86_64 file to the /os-images folder on the data partition of the removable drive. See the get-tools.sh script to handle this automatically.

Inspiration and Thanks

We found these docs very helpful:

• https://www.gnu.org/software/grub/manual/grub/html_node/index.html
• https://wiki.archlinux.org/title/Multiboot_USB_drive

Also cribbed a number of grub scripting techniques from these similar projects:

• https://github.com/aguslr/multibootusb
• https://github.com/hackerncoder/multibootusb
• https://github.com/thias/glim

Not to mention looking at the grub.cfg of the many ISO images themselves.

Contributing Support Files

Need support for your favorite distro? Please make a merge request with your menuentry stanza in a name.cfg file under the support folder of this repo. The script filename must match the prefix of the boot image filename, up until the first dash or period -., with a .cfg extension at the end. e.g.: foobar-123.iso --> ./support/foobar.cfg

I suggest getting started by looking in the last two repos linked above for example boot commands and arguments for your product of choice. Also, mount your .iso file of interest as a loopback drive or open with an archiver. Looking around the folders will give quite a bit of information, such as the proper paths to the kernel etc.

Then, refactor the script using the guidelines below.

Tools

Please use these tools before submission:

• shellcheck *.sh, for bash and
• grub*-script-check, for .cfg files, for example:

find . -name '*.cfg' -print -exec grub-script-check '{}' ';'

You will find them annoying and helpful.