.\" -*- nroff-fill -*-
.\" $FreeBSD$
.Dd December 23, 1999
.Os FreeBSD
.Dt PicoBSD 8
.Sh NAME
.Nm picobsd
.Nd Floppy disk based FreeBSD system
.Sh SYNOPSIS
.Nm
.Op Fl n
.Op Ar floppy-type Op Ar site-name
.Pp
.Sh DESCRIPTION
.Nm
is a minimal implementation of
.Fx
on one or more floppy disks.  The
floppies are required for loading only; the system runs from ramdisk and is thus
not limited to the speed of the floppies.
The first (and only required)
.Nm
floppy contains a compressed kernel and compressed MFS root file system, as well
as some files in the
.Pa /etc
directory.  The system loads the kernel in the normal way, uncompresses the file
system and mounts it as root.  It then copies the files in the floppy
.Pa /etc
directory to the MFS
.Pa /etc
directory and executes a specialized version
.Pa /etc/rc .
The standard version of
.Pa /etc/rc
prompts for additional floppies and reads them in to the MFS file system.
.Sh ENVIRONMENT
As a result of the extreme size limitations, the
.Nm 
environment differs from the normal
.Fx
in a number of ways:
.Bl -bullet
.It
There are no dynamic libraries, and there is no directory
.Pa /usr/lib .
As a result, only static executables may be executed.
.It
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 .
.It
Some programs are supplied in minimalistic versions, specifically
.Nm ns ,
a cut-down version of
.Nm netstat ,
and
.Nm vm ,
a cut-down version of
.Nm vmstat .
.El
.Sh BUILDING picobsd
The
.Nm
sources reside in the hierarchy
.Pa /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. In FreeBSD 4.3, the supported build script is
.Pa /usr/src/release/picobsd/build/picobsd
which can be run from anywhere.
This interactive script will ask for parameter entries and then build the
appropriate single floppy version. The following kinds of floppy are envisaged:
.Bl -hang
.It bridge
is a configuration suitable for bridges, routers and firewalls
.It dial
is a configuration suitable for dial-out (ppp) networking.
.It install
is a configuration suitable for software installation.
.It isp
is a configuration suitable for dial-in (ppp) networking.
.It net
is a configuration suitable for general networking.
.It router
is a configuration suitable for use as a router.  This particular configuration
aims to work on minimal hardware.
.El
.Pp
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.
.Pp
You can define your own floppy type, by creating a directory
with a name of your choice (e.g. FOO) which contains
.Pp
.Bl -tag -width "floppy.tree.exclude" -compact
.It PICOBSD
the kernel configuration file (required).
.It crunch.conf
crunchgen configuration (required).
.It config
shell variables, sourced by the "picobsd" script (optional).
.It floppy.tree.exclude
files from the standard floppy tree which are not needed (optional).
.It floppy.tree/
local additions to the standard floppy tree (optional).
.It floppy.tree.${site}
same as above, site-specific (optional).
.El

More information on the build process can be found in
the "picobsd" script.
Sample configurations can be found in
.Pa /usr/src/release/picobsd/${type}/

.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.
.Pp
To speed up booting, you can use
.Xr 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.
minutes.
.Ss Swap space
After booting,
.Nm
runs entirely from the MFS 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.
.Pp
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 STANDARDS
.\" .Sh HISTORY
.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 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
.Nm vn
driver installed.  
.Pp
The build process must be run as
.Nm root
because of the need of running vnconfig and mount.
.Pp
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.