.\" -*- nroff-fill -*-
.\" $FreeBSD$
.Dd 23 December 1999
.Os FreeBSD
.Dt PicoBSD 8
.Sh NAME
.Nm PicoBSD
.Nd Floppy disk based FreeBSD system
.Sh SYNOPSIS
.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.
.Sh DESCRIPTION
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 is designed to be flexible in order to cram as much as possible on
to the floppies.  In particular, the following possibilities exist:
.Bl -bullet
.It
The old style of building uses a script called 
.Pa build/build .
To use it, change directory to
.Pa build/
and run
.Cm build .
.Cm build
is an interactive script which will ask for parameter entries and then build the
appropriate single floppy version.  Five kinds of floppy are envisaged:
.Bl -hang
.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
.It
The new style of building uses
.Cm make .
The file
.Pa Makefile
will build in the directory
.Pa custom .
.El
.Pp
The build process involves the following steps.  In the examples, the
subdirectory
.Pa custom 
is used, but the principle also applies to the subdirectories
.Pa dial ,
.Pa install ,
.Pa isp ,
.Pa net
and 
.Pa router .
.Bl -hang
.It Em Build the kernel.
Each directory contains a configuration file with a name starting with
.Pa PICOBSD .
When building a custom
.Nm PicoBSD ,
it is important to review this file carefully.  The smallest possible kernel
occupies about 600 kB after compression, and it is easy to have a kernel as
large as 900 kB.  It is probably not possible to build a first
.Nm
floppy with a kernel of 900 kB.
.It Em Create the MFS image.
The MFS image for the first floppy is created as a
.Nm vnode
file system which is subsequently mounted as
.Pa /dev/vn0 
on
.Pa custom/mmnt .
.It Em Create the crunched executables.
The executables for the first floppy are built in the directory
.Pa crunch/crunch1/ .
The contents of this executable are determined by the file
.Pa crunch/crunch1/crunch.conf .
.It Em Build the floppy image.
A second file system image, which will later become the first floppy, is built
and mounted as 
.Pa /dev/vn1
on
.Pa custom/fmnt .
It receives the compressed kernel, the compressed MFS file system, the contents
of the tree
.Pa floppy.tree/ 
and
.Pa floppy.tree/custom/
if the latter directory exists.  This dual method allows specific files in
.Pa floppy.tree/custom/ 
to overlay files from 
.Pa floppy.tree/ .
.It Em Create the image for the second floppy.
Finally, the image for the second floppy is built.  There is only one file on
this floppy, which will be copied to the MFS-relative directory 
.Pa /bin
at boot time.  The contents are built in the directory
.Pa crunch/crunch2/ .
The contents of this executable are determined by the file
.Pa crunch/crunch2/crunch.conf .
.It Em Copy the data to the floppies.
The previous steps are performed by the
.Nm make all
step.
.Nm make all
does not copy data to the floppy disks.  Instead, use
.Nm make floppy 
for the first floppy, and
.Nm make floppy2
for the second disk.
.It Em Create additional floppies.
You can theoretically possible to read a large number of floppies into the MFS.
Each additional floppy, including the second, is a gzipped tar file containing
files relative to
.Pa /bin .
You can put any statically linked program on a floppy in this form, and the
startup routines will automatically read it in.  Remember that there are no
dynamic libraries, so the programs must be static.
.El
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" This next request is for sections 1, 6, 7, 8 & 9 only
.\"     (command return values (to shell) and
.\"       fprintf/stderr type diagnostics)
.\" .Sh DIAGNOSTICS
.\" The next request is for sections 2, 3 and 9 error
.\" and signal handling only.
.\" .Sh ERRORS
.Sh BOOTING PicoBSD
To boot
.Nm PicoBSD ,
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 prompt for the second floppy takes about 3
minutes.
.Pp
When the prompt for additional floppies appears, first insert the floppy in the
drive, then answer
.Em y .
When you have no more floppies, enter
.Em n .
This version of
.Nm
does not have a root password.  If you require greater security, you can copy
your own
.Pa /etc/master.passwd
and possibly
.Pa /etc/group
to the first boot floppy.  These are the only files you need: the boot process
generates the files
.Pa /etc/passwd ,
.Pa /etc/spwd 
and
.Pa /etc/pwd.db 
automatically.
.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 PicoBSD .
Use the
.Xr swapon 8
command.
.Sh RECOVERING CRASHED SYSTEMS
The
.Em custom
.Nm
configuration contains all the programs that are present on the
.Em fixit 
floppy, so you can use it instead of the fixit floppy.
.Sh SEE ALSO
.Xr crunchgen 1 ,
.Xr swapon 8 ,
.Xr vnconfig 8
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
.An Andrzej Bialecki Aq abial@FreeBSD.org .
Man page and Makefiles created by
.An Greg Lehey Aq grog@lemis.com .
.Sh BUGS
In order to build 
.Nm PicoBSD ,
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 .
.Pp
The build process does not search for unused vnode devices; it uses
.Pa /dev/vn0
and
.Pa /dev/vn1 .
If these files are not in use by other programs, unexpected behaviour may
result.
.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.
.Pp
The original version of 
.Nm
fits on one floppy.  Since
.Fx 4.0 ,
the kernel is so large that most
configurations will need a second floppy to do any productive work.
Nevertheless, it should be possible to create minimal kernels which will fit
alongside sufficient other programs on a single floppy.
.Pp
The approach of building executables with
.Xr crunchgen 1
means that considerable duplication of libraries occurs between the floppies.
.Pp
At the current time (December 1999), the old-style build is broken in
.Fx Ns -CURRENT .
In view of the significant increase in size of the 4.x kernel
compared to the 3.x kernel, it is not certain that it can be fixed.
.Pp
.Nm
has suffered some bit rot in 1999, and currently most of the old-style
configurations do not build.
.Pp
There appears to be no way to get
.Nm Emacs
to run on
.Nm PicoBSD .