Please read this entire file before asking for help or reporting bugs
This is a small infrastructure to build minimal OpenBSD installations suitable for booting of flash devices. This is derived from the scripts and tools used to build the OpenBSD installation media.
The system builds a ram-disk kernel (bsd.gz) with a reasonably complete set of daemons and utilities. This file should be installed into the root directory of the boot device. Note that this infrastructure only builds the kernel image, it is beyond its scope to install it onto the flash device, or to prepare the flash device for booting the kernel. If you are playing with this stuff, you should know how to do this anyway.
When the flashboot kernel boots, it will attempt to mount the flash device as /flash and extract any tarball files matching /flash/.tgz into the root directory. This mechanism is intended to include the system configuration that the host will use, though it may be used to deploy updated or new binaries too. The configuration parameters accepted include most of the standard OpenBSD /etc/ files, including /etc/hostname. and a useful subset of /etc/rc.conf. See the initial-conf/rc script for details. As well as extracting /flash/*.tgz, the init script will copy any files under the /flash/conf/ directory to the root too - I find this a little more convenient for small config files that frequently change (e.g. pf.conf).
In the absence of a tarball or directory-based config, the system is configured with a basic initial configuration. The first Ethernet interface is brought up as 192.168.0.1 and the console is available (login: "root" password: "password"). The intention is to make it easy to load a real config from a freshly imaged flash card.
The assumed platform is a Soekris NET4501 (www.soekris.com), but is very easily changed by selecting a different kernel config and adjusting or renaming the initial-conf/hostname.sis0 file.
To install flashboot onto your media, you will need to format it and make it bootable first. Read the fine boot(8) and installboot(8) manpages for instructions on how to prepare the media.
Once the media is setup as bootable, you can just copy the kernel image to /bsd on the mounted device. You should also create a /conf directory to store your custom configuration - files under here are copied into the ramdisk at system boot time. After startup the boot device is mounted as /flash in the root of the ramdisk, so you can make changes at runtime there.
To influence the boot loader, you can create a /etc/boot.conf file on the root of the bootable media (not /conf/etc/boot.conf). You can use the standard boot.conf(5) options, such as changing console device and speed here.
(if the following sounds too hard, please use the binary distribution of flashboot, available from the website)
A built release of OpenBSD is required for this infrastructure to work. To save space, you will probably want to turn off compile-time options such as Kerberos support. The current version of flashboot requires that you have built the entire system as dynamically linked, i.e. set STATIC= in mk.conf. Previous flashboot versions used crunchgen, but fully-dynamic saves 1.5Mb.
Here are the basic steps you need to take.
First, download the source from ftp (or a cd) and install it in /usr/src
# cd /usr/src
# tar xzf sys.tar.gz
# tar xzf src.tar.gzBuild crunch and crunchgen, these utilities are used when building the kernel.
# cd /usr/src/distrib/crunch && make obj depend all installMost of this work can be done for you using mk-mini.conf and
build-release.sh. The build-release.sh is prepped so that if you
execute it, it will build the dynamic release in the current dir.
If you are storing your src & sys-folders somewhere else, then
you will have to edit build-release.sh. This build can take a very
long time. (Make sure you run this in the flashdist-directory)
# ./build-release.shWhen the building is done you should have a fully dynamic release in flash-disk and flash-obj. Now it's time to make your disk image file. The build-bindinst.sh takes a kernel-config as a parameter. Currently COMMELL-LE564, FBII, FBIII, FBX500-2500, GENERIC-RD, NTFS, SOEKRIS4501, SOEKRIS4521, SOEKRIS4801, SOEKRIS5501, WJ-200 and WRAP12 configs are provided. You can easily make your own by copying one of the existing.
# ./build-bindinst.sh FBIII The image is then stored under the Output/ directory, there are two files that get created, the image file is used to dd or using physdiskwrite to put onto CF media, the update file is the image that can be sent to an already configured box via the webui to load the newly created system partition
The system support customisation in three different ways.
Any file that you add to the root of the flash-card (/flash) that has the tgz-extension is automatically extracted to the ramdisk during boot. This is useful for small extensions or configuration that you can distribute in a single tgz-package. Files can also be added to the /flash/conf directory, they are then automatically copied (not extracted) to the ramdisk during boot.
There is also an option in rc.conf to create a second ramdisk in /usr/local. By default this is not done at all to save memory on the device. If activated this will also extract any files located in /flash/pkg/ ending with the tgz-extension to /usr/local. This provides an excellent way to add packages directly from the OpenBSD ftp-server without needing to expand the original ramdisk. The rc-script will even remove some unnecessary files from the packages such as man-pages and files needed only for compiling.
Recompile a kernel that suits your needs and that includes or excludes the binaries and libs that you need for your application. Change the list to include extra files. You can also use the script build-largekernel.sh which is an exact copy of the build-kernel.sh with the difference that it creates a 25MB ramdisk instead of a ~15 MB kernel. It also includes the content of the list.largekernel-file to include some extra binaries and libs that does not fit in the original distribution. If you have decided to go down this road you might just as well modify the default configuration located under the initial-conf directory.
The first two alternatives can be done without having to recompile the distribution and should be sufficient for most needs. But on devices that do not have the memory concern, there should be much easier to do build the larger kernel and add stuff as you need them.
Kernelsizes are a problem when piggybacking a ramdisk blob. Kernel+ramdisks larger than 16MB needs to increase the NKPTP in the kernel config. This is already done for all the kernels and you shouldn't have to do anything as long as you stay under 32MB. The second problem is that kernels larger than about 14MB will use up all the ISA DMA memory, for this reason ISA DMA is disabled. This leads to the final problem: if isadma is disabled, then things that attempt to use it (e.g. floppy disk access) will panic the kernel. In the end the best solution is to try to keep your kernels small.
This infrastructure does a couple of things to save space, but is not at all ferocious as I stopped tweaking once I reached my target (bsd.gz < 5Mb). To save space, only a couple of term{cap,info} entries are transferred (see TERMTYPES in the Makefile).
To create an iso image suitable for booting and running flashboot on a x86 PC, first read the build instructions above. Step 1 and 2 must be successfull and in step 3 use the build-livecd.sh script with the GENERIC-RD kernel config.
# ./build-livecd.sh GENERIC-RDThe build-live_cd.sh script will create the directory live_cd before creating the image. Everything in this directory will be included on the cd. The files cdbr, cdboot etc/boot.conf is required for booting. To customize the cd with additional data, create the directory live_cd in advance and populate with data and modify rc.{init|more} as needed. The build-livecd.sh will use the default flashboot config files and make modifications prior to ramdisk creation. Any customisation to ramdisk setup should be done by editing build-livecd.sh.
If everything worked then you should find a new iso image in obj/live_cd{version}.iso. Without any customisation the iso is roughly 9MB in size. Finally... burn the iso with your favorite cd burning program.
Please send bug reports to djm@mindrot.org or subscribe to the mailinglist flashboot@mindrot.org. I don't have time to support this software, so if you run into problems you are on your own. This code works very well for me, so hopefully it will for you too.
Damien Miller djm@mindrot.org
http://www.mindrot.org/flashboot.html
$Id: README,v 1.2 2009/03/02 21:55:46 jrecords Exp $