$FreeBSD: head/share/man/man8/picobsd.8 55069 1999-12-24 00:16:03Z grog $
.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 FreeBSD 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
a /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
a /etc directory to the MFS
a /etc directory and executes a specialized version
a /etc/rc . The standard version of
a /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 FreeBSD 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 .Nm crunchgen(1) . t 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
a /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: l -bullet t The old style of building uses a script called
a build/build . To use it, change directory to
a 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: l -hang 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 t The new style of building uses .Cm make . The file
a Makefile will build in the directory
a custom . .El
p The build process involves the following steps. In the examples, the subdirectory
a custom is used, but the principle also applies to the subdirectories
a dial ,
a install ,
a isp ,
a net and
a router . l -hang t Em Build the kernel. Each directory contains a configuration file with a name starting with
a 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. t 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
a custom/mmnt . t Em Create the crunched executables. The executables for the first floppy are built in the directory
a crunch/crunch1/ . The contents of this executable are determined by the file
a crunch/crunch1/crunch.conf . t Em Build the floppy image. A second file system image, which will later become the first floppy, is built and mounted as
a custom/fmnt . It receives the compressed kernel, the compressed MFS file system, the contents of the tree
a floppy.tree/ and
a floppy.tree/custom/ if the latter directory exists. This dual method allows specific files in
a floppy.tree/custom/ to overlay files from
a floppy.tree/ . t 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
a /bin at boot time. The contents are built in the directory
a crunch/crunch2/ . The contents of this executable are determined by the file
a crunch/crunch2/crunch.conf . t 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. t 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
a /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 FreeBSD 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.
p 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
a /etc/master.passwd and possibly
a /etc/group to the first boot floppy. These are the only files you need: the boot process generates the files
a /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.
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 PicoBSD .
Use the
.Nm 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
Andrzej Bialecki <abial@FreeBSD.org>. Man page and Makefiles created by Greg
Lehey <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.
p The build process must be run as .Nm root .
p The build process does not search for unused vnode devices; it uses
a /dev/vn1 . If these files are not in use by other programs, unexpected behaviour may result.
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.
p The original version of .Nm fits on one floppy. Since FreeBSD 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.
p The approach of building executables with .Nm crunchgen(1) means that considerable duplication of libraries occurs between the floppies.
p At the current time (December 1999), the old-style build is broken in FreeBSD -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.
p .Nm has suffered some bit rot in 1999, and currently most of the old-style configurations do not build.
p There appears to be no way to get .Nm Emacs to run on .Nm PicoBSD .