New man page. This will need modifications RSN.

svn path=/head/; revision=55069

share/man/man8/picobsd.8

@@ -0,0 +1,282 @@
+.\" -*- 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 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
+.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 FreeBSD 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
+.Nm 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 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.
+.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
+.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.  
+.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 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.
+.Pp
+The approach of building executables with
+.Nm 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 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.
+.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 .