resflash

Resilient OpenBSD images for USB flash memory

Resflash is a tool for building reproducible OpenBSD images for embedded and cloud platforms with easy, single-file upgrades. Resflash uses read-only and memory-backed filesystems, and because the filesystems are written to only during system upgrades, they are not subject to corruption or fsck due to power loss - and even cheap USB flash drives can last virtually forever. Resflash images can be written to any bootable media (flash or conventional) and make great firewall, NAS, or VM server boot drives. Resflash was written from scratch, with inspiration drawn from NanoBSD and flashrd.

Features

Features unique to resflash

How does it work?

Resflash images contain two main data partitions, one active and one inactive. During the upgrade process, the inactive partition is updated, tested, and set active for the next boot. A /cfg partition can be used to store modifications from the mfs filesystems (/etc and /var) and are overlaid at boot time. Small /mbr, /efi, and /ofw partitions are used to maintain the BIOS, UEFI, and Open Firmware boot code, respectively.

Coverage

Downloads

Usage

  1. Create an OpenBSD base directory with a minimum of the following:

    Sets must be unpacked as root using tar zxfph set.tgz.

  2. Run build_resflash.sh:

    usage: build_resflash.sh [-p pkg_dir] [-s com0_speed (sets com0 console)]
                             [--pkg_path path1:path2 --pkg_list pkg1,pkg2]
                             img_size_in_mb openbsd_base_dir
    
  3. Write the .img file (not the .fs file) to the drive: dd if=resflash-amd64-com0-115200-20yymmdd_HHMM.img of=/dev/rsd3c bs=1m

Sample output:

resflash 6.1.3

Validating OpenBSD base dir: /usr/local/rdest
Creating disk image: resflash-amd64-com0-115200-20170405_1928.img
Creating filesystem: resflash-amd64-com0-115200-20170405_1928.fs
Populating filesystem and configuring fstab
Running fw_update
Installing packages: /usr/local/rpkg
Writing filesystem to disk image and calculating checksum
Compacting disk image and calculating checksum
Build complete!

File sizes:
410M    resflash-amd64-com0-115200-20170405_1928.fs
953M    resflash-amd64-com0-115200-20170405_1928.img
Disk usage:
241M    resflash-amd64-com0-115200-20170405_1928.fs
244M    resflash-amd64-com0-115200-20170405_1928.img

Upgrades

Unlike the initial installation, upgrades use .fs filesystem files. Upgrades take place by piping the .fs file through the /resflash/upgrade.sh script. This can be accomplished in many ways:

Sample output:

Writing filesystem to inactive partition
CemfdpkYKiM+fPT6v8UiVsncSw2OEmRuc7rMaBIqn/yy+gNSY5Dnh/GBBthKUuw+1gW3sIb5NRWRkg78
x/zgpQ==
Checking filesystem
/dev/rsd0e: 10713 files, 160289 used, 285134 free (134 frags, 35625 blocks, 0.0%
fragmentation)
Updating fstab
Updating MBR
Updating biosboot(8) and boot(8)
Everything looks good, setting the new partition active
Upgrade complete!

Other build tools

Host tools

Problems?

Resflash is not a supported OpenBSD configuration. Please do not email misc@ asking for help. If you have a question or a bug to report, please post to the mailing list, submit an issue on GitLab, or email me directly.

Support OpenBSD

This project would not be possible without the work of the fine folks at OpenBSD. Please support them with a donation or purchase.

FAQ

What is the root password for the premade images?

As resflash uses an unmodified OpenBSD operating system, there is no root password by default. Hit enter at the password prompt to log in as root. You will need to set a root password before logging in remotely via SSH.

What is the difference between the .img and .fs files?

The .img files are disk images, including MBR partition tables, that are used for initial installation to a flash drive. The .fs files are filesystems that are used for in-place upgrades by /resflash/upgrade.sh.

How do I use the /cfg partition?

The /cfg partition is usually unmounted and stores modifications to the /etc and /var mfs filesystems. Files are saved either manually or on shutdown according to /etc/resflash.conf. To manually save a file, mount /cfg and then copy any file you want re-populated to /cfg/etc or /cfg/var, retaining the directory structure (i.e. /cfg/etc/hostname.em0 or /cfg/etc/ssh/sshd_config). Unmount /cfg when finished. You can also run /resflash/resflash.save manually to save configured files at any time.

What about LBA and CHS?

Resflash requires an LBA-aware BIOS. CHS numbers have been bogus for 20 years, and I don't have the hardware for - or much interest in - supporting them. Make sure to set your Alix board to LBA mode. If you have a use case for a CHS-only device that needs supporting, I'd be interesting in hearing about it.

Does the build_resflash.sh image size matter if I'm only building .fs files for upgrades?

Yes! Filesystem sizes are calculated from image size, so you will want to keep your image size consistent over the life of an image (see /resflash/BUILD if you forget). You can scale image size down without issue, but if you attempt to use a filesystem from a larger image for an upgrade, the filesystem will exceed the available space of the inactive partition, and the upgrade will fail.

Help! I ran the upgrade and now it won't boot. How do I failover to the previous version?

At the OpenBSD boot prompt, enter set device hd0d and press enter, assuming that the 'e' partition is your upgraded partition that is failing to boot. If 'd' is failing, set it to hd0e. Before doing any diagnosis on your failed upgrade, you will want to mount /mbr and edit /mbr/etc/boot.conf to point to the working boot device.

Should I customize the .img file prior to writing to disk, or via /cfg?

There is no wrong answer here. If you're scripting your builds, it probably makes sense to use the (u)mount_resflash.sh tools to make all your changes to the .img or .fs directly, and then use /cfg exclusively for runtime files (i.e. /var/db/host.random). If you're using resflash for a single system, it's perfectly reasonable to save things like myname or hostname.em0 in /cfg/etc. If you need to modify files outside of /etc or /var, such as /root, that is best done via the .img or .fs file.

How do I install on octeon?

First, write a .img to the system's USB storage. There are two ways to do this:

Next, from within the U-Boot menu, run setenv bootcmd 'usb reset; fatload usb 0 $loadaddr bsd; bootoctlinux $loadaddr coremask=0x3 rootdev=sd0'. You may also wish to run setenv bootdelay 5. Save the changes and reboot with saveenv and reset.

How do I boot macppc from USB?

Enter Open Firmware by holding Cmd-Alt-o-f on boot. Set your USB drive as the boot device by running setenv boot-device ud:,ofwboot. Finally, reset-all will save the changes and reboot. If your version of Open Firmware is too old to support a ud alias, you will need to follow the steps listed here (dev / ls, find the USB entry with a /disk attached to it, look up that entry in devalias). You will likely end up with something like setenv boot-device usb1/disk@1:1,ofwboot.