$FreeBSD: head/share/man/man8/picobsd.8 90682 2002-02-15 07:47:39Z luigi $
.Dd June 20, 2001 .Os .Dt PICOBSD 8 .Sh NAME .Nm picobsd .Nd floppy disk based FreeBSD system .Sh SYNOPSIS .Nm .Op options .Op Ar floppy-type Op Ar site-name .Sh DESCRIPTION .Nm is a script which can be used to produce a minimal implementation of .Fx (historically called .Nm PicoBSD ) which typically fits on one floppy disk, or can be downloaded as a single image file from some media such as CDROM, flash memory, or through .Xr etherboot .
p .Nm picobsd has been 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.
p 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.
p The system loads the kernel in the normal way, uncompresses the memory file system and mounts it as root. It then updates the memory filesystem with files from the boot media (if present), and executes a specialized version of
a /etc/rc . The boot media (floppy etc.) is required for loading only, and typically used as readonly. After the boot phase, the system runs entirely from ram.
p The following options are available (but also check the .Nm script for more details):
p l -tag -width "xxxxxx" -compact t Fl -src Ar SRC_PATH Use the source tree at .Ar SRC_PATH instead the one at .Ar /usr/src . Can be useful for cross-building floppy images. When using this option, you must also create initialize the subtree at .Ar SRC_PATH/../usr with the correct include files, libraries and tools (such as the .Xr config 8 program) that are necessary for the cross-build (see the .Fl -init option below). The source files are unmodified by the .Nm picobsd script. However the source tree is not completely readonly, because .Xr config 8 expects the kernel configuration file to be in one of its subdirectories, and also the process of initializing the .Ar usr subtree touches some parts of the source tree (this is a bug in the release build scripts which might go away with time).
p t Fl -init When used together with the .Fl -src option, it initializes the .Ar SRC_PATH/../usr subtree as necessary to subsequently build picobsd images.
p t Fl -modules Also build kernel modules. They are not stored on the floppy image but are left available in the build directory.
p t Fl n Make the script non interactive. Do not show the initial menu, and proceed in the build process without requiring user input.
p t Fl v Make the script verbose, showing the various commands to execute and waiting for user input before each of them. Useful when debugging.
p t Fl -all_in_mfs Puts the entire content of the filesystem in the memory filesystem image which is contained in the kernel. This is the default behaviour, and is extremely useful as the kernel itself can be loaded using .Xr etherboot or .Xr pxeboot to have a fully functional system.
p t Fl -no_all_in_mfs Leaves files contained into the .Ar floppy.tree on the floppy image, so they can be loaded separately from the kernel (and updated individually to customize the floppy image).
p t Fl -floppy_size Ar size Set the size of the floppy image. Values other than 1440 can be used for images that are burned into a CDROM.
p t Fl c t Fl clean Clean the product of previous builds. .Xr etherboot .El .Sh ENVIRONMENT As a result of the extreme size limitations, the .Nm environment differs from the normal .Fx in a number of ways: l -bullet t There are no dynamic libraries, and there is no directory
a /usr/lib . As a result, only static executables may be executed. t In order to reduce the size of the executables, all executables on a specific floppy are joined together as a single executable built with .Xr crunchgen 1 . t Some programs are supplied in minimalistic versions, specifically .Nm ns , a cut-down version of .Xr netstat 1 , and .Nm vm , a cut-down version of .Xr vmstat 8 . .El .Sh BUILDING picobsd The .Nm sources reside in the hierarchy
a /usr/src/release/picobsd . In the following discussion, all relative path names are relative to this directory. The .Nm build process has changed slightly over time, in order to cope with the unavoidable increase of code size, which requires more and more tricks to cram as much as possible on to the floppies. Starting from .Fx 4.3 , the supported build script is
a /usr/src/release/picobsd/build/picobsd which can be run from anywhere. When run in interactive mode (the default without the .Fl -n option), the script will let you configure the various parameters used to build the floppy image. The following kinds of floppy are envisaged, and we try to keep them functional and fitting in the 1.44MB floppy despite the unavoidable increases in the size of the kernel and its applications: l -hang -width "install " t bridge is a configuration suitable for bridges, routers and firewalls .El
p The following configurations are also present but for reference only. Many of them are irrimediably out of date and no effort is done to keep them in good shape: l -hang -width "install " t dial is a configuration suitable for dial-out (ppp) networking. t install is a configuration suitable for software installation. t isp is a configuration suitable for dial-in (ppp) networking. t net is a configuration suitable for general networking. t router is a configuration suitable for use as a router. This particular configuration aims to work on minimal hardware. .El
p These configurations serve only as examples to build your own. 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.
p 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 .Nm picobsd configurations as a reference.
p l -tag -width "xxxxx" -compact t Pa PICOBSD The kernel configuration file (required). This is a mostly standard kernel configuration file, possibly stripped down by removing unnecessary drivers and options to reduce the kernel's size.
p To be recognised as a .Nm kernel config file, the file must also contain the line beginning with #PicoBSD below, and a matching MD_ROOT_SIZE option:
p d -literal -offset indent #marker def_sz init MFS_inodes floppy_inodes #PicoBSD 4200 init 8192 32768 options MD_ROOT_SIZE=4200 # same as def_sz .Ed
p to inform the script on the size of the memory filesystem and a few other information on how to build the image.
p t Pa crunch.conf crunchgen configuration (required). See the .Xr crunchgen 1 manpage for the syntax.
p t Pa config shell variables, sourced by the
a picobsd script (optional). Again, look at the standard
p t Pa floppy.tree.exclude files from the standard floppy tree which are not needed (optional).
p t Pa floppy.tree/ local additions to the standard floppy tree (optional).
p t Pa floppy.tree. Ns ${site} same as above, site-specific (optional). .El
p More information on the build process can be found in the comments in the
a picobsd script. Sample configurations can be found in
a /usr/src/release/picobsd/ Ns ${type} Ns / .Sh USING ALTERNATE SOURCE TREES The build script can be instructed use an alternate source tree using the .Fl -src Ar SRC_PATH option. The tree that you specify must contain full sources for the kernel and for all programs that you want to include in your image. As an example, to cross-build the "bridge" floppy using RELENG_4 sources, you can do the following: d -literal -offset indent cd <some_empty_directory> mkdir FOO (cd FOO; cvs -d <my_repository> co -r RELENG_4 src ) picobsd --src FOO/src --init # this is needed only once picobsd --src FOO/src -n -v bridge .Ed
p If the build is successful, the directory .Ar build_dir-bridge/ will contain a .Ar kernel that can be downloaded with .Xr etherboot 8 , a floppy image called .Ar picobsd.bin , plus the products of the compilation in other directories. If you want to modify the source tree in .Ar FOO/src , a new image can be produced by simply running d -literal -offset indent picobsd --src FOO/src -n -v bridge .Ed
p whereas if the change affects include files or libraries you first need to update them e.g. by running first d -literal -offset indent picobsd --src FOO/src --init # this is needed only once .Ed
p as you would normally do for any change of this kind.
p .Sh BOOTING PicoBSD To boot .Nm , insert the floppy and reset the machine. The boot procedure is similar to the standard .Fx boot, but proceeds at a snail's pace. From the end of the POST (BIOS Power On Self Test) until the system is up and running takes anywhere between 1 and 3 minutes.
p To speed up booting, you can use .Xr etherboot to load the preloaded, uncompressed kernel image which is a byproduct of the .Nm build. In this case the load time is a matter of a few seconds, even on a 10Mbit/s ethernet. .Ss Swap space After booting, .Nm runs entirely from the memory file system. The floppies are no longer used, and even if there are hard disk drivers in the .Nm kernel, it does not access the drives. In particular, there is no swap space, so if you run out of memory, unpredictable things can happen.
p If you have a disk driver and a disk with a swap partition on it, and the swap partition does not contain a dump you want to keep, you can use this swap with .Nm . Use the .Xr swapon 8 command. .Sh SEE ALSO .Xr crunchgen 1 , .Xr swapon 8 , .Xr vnconfig 8 .Sh AUTHORS .An -nosplit .An Andrzej Bialecki Aq abial@FreeBSD.org , with subsequent work on the scripts by .An Luigi Rizzo Aq luigi@iet.unipi.it and others. Man page and
a Makefiles created by .An Greg Lehey Aq grog@lemis.com . .Sh BUGS In order to build .Nm , the kernel of the system on which it is built must have the .Xr vn 4 driver installed.
p The build process must be run as .Dq root because of the need of running .Xr vnconfig 8 and .Xr mount 8 .
p Building .Nm is still a black art. The biggest problem is determining what will fit on the floppies, and the only practical method is trial and error.