CONTENTS

SYNOPSIS

DESCRIPTION

The picobsd utility was originally created to build simple standalone systems such as firewalls or bridges, but because of the ability to cross-build images with different source trees than the one in the server, it can be extremely useful to developers to test their code without having to reinstall the system.

The boot media (typically a floppy disk) contains a boot loader and a compressed kernel which includes a memory file system. Depending on the media, it might also contain a number of additional files, which can be updated at run time, and are used to override/update those in the memory file system.

The system loads the kernel in the normal way, uncompresses the memory file system and mounts it as root. It then updates the memory file system with files from the boot media (if present), and executes a specialized version of /etc/rc. The boot media (floppy, etc.) is required for loading only, and typically used read-only. After the boot phase, the system runs entirely from RAM.

The following options are available (but also check the picobsd script for more details):

ENVIRONMENT

• There are no dynamic libraries, and there is no directory /usr/lib. As a result, only static executables may be executed.
• In order to reduce the size of the executables, all executables on a specific floppy are joined together as a single executable built with crunchgen(1).
• Some programs are supplied in minimalistic versions, specifically ns, a cut-down version of netstat(1), and vm, a cut-down version of vmstat(8).

BUILDING PicoBSD

The following configurations are also present but for reference only. Many of them are irremediably out of date and no effort is done to keep them in good shape:

These configurations serve only as examples for your own modification. Not all of them have been tested, and you might need small tweaks to the configuration files to make them work or even fit into the available disk space as code size increases.

You can define your own floppy type, by creating a directory with a name of your choice (e.g. FOO) which contains some of the following files and directories. For more information on how to construct these files, look at one of the standard picobsd configurations as a reference.

If the build is successful, the directory build_dir-bridge/ will contain a kernel that can be downloaded with etherboot, a floppy image called picobsd.bin, plus the products of the compilation in other directories. If you want to modify the source tree in FOO/src, a new image can be produced by simply running

"picobsd --src FOO/src -n -v bridge"

whereas if the change affects include files or libraries you first need to update them, e.g. by running first

"picobsd --src FOO/src --init # this is needed only once"

Floppy Install

"dd if=picobsd.bin of=/dev/rfd0"

The first form will install the image on the entire disk, and it should work in the same way as for a floppy.

The second form will install the image on slice number 3 (which should be large enough to store the contents of the image). However, the process will only have success if the partition does not contain a valid disklabel, otherwise the kernel will likely prevent overwriting the label. In this case you can use the third form, replacing NN with the actual start of the partition (which you can determine using fdisk(8)). Note that after saving the image to the slice, it will not yet be recognised. You have to use the disklabel(8) command to properly initialize the label (do not ask why!). One way to do this is
disklabel -w ad0s2 auto
disklabel -e ad0s2

and from the editor enter a line corresponding to the actual partition, e.g. if the image has 2.88MB (5760 sectors) you need to enter the following line for the partition:

"a: 5760 0 4.2BSD 512 4096"

BOOTING PicoBSD

You can also use etherboot to load the preloaded, uncompressed kernel image which is a byproduct of the picobsd build. In this case the load time is a matter of a few seconds, even on a 10Mbit/s ethernet.

After booting, picobsd loads the root file system from the memory file system, starts /sbin/init, and passes control to a first startup script, /etc/rc. The latter populates the /etc and /root directories with the default files, then tries to identify the boot device (floppy, hard disk partition) and possibly override the contents of the root file system with files read from the boot device. This allows you to store local configuration on the same media. After this phase the boot device is no longer used, unless the user specifically does it.

After this, control is transferred to a second script, /etc/rc1 (which can be overridden from the boot device). This script tries to associate a hostname to the system by using the MAC address of the first ethernet interface as a key, and /etc/hosts as a lookup table. Then control is passed to the main user configuration script, /etc/rc.conf, which is supposed to override the value of a number of configuration variables which have been pre-set in /etc/rc.conf.defaults. You can use the hostname variable to create different configurations from the same file. After taking control back, /etc/rc1 completes the initializations, and as part of this it configures network interfaces and optionally calls the firewall configuration script, /etc/rc.firewall, where the user can store his own firewall configuration.

There is a small script called update which can be used to edit and/or save to disk a copy of the files you have modified after booting. The script takes one or more absolute pathnames, runs the editor on the files passed as arguments, and then saves a compressed copy of the files on the disk (mounting and unmounting the latter around the operation).

If invoked without arguments, update edits and saves rc.conf, rc.firewall, and master.passwd.

AUTHORS

BUGS