From 587357da148de4bbd5dc65fab5e5b38a9a5522a6 Mon Sep 17 00:00:00 2001 From: Greg Lehey Date: Fri, 24 Dec 1999 00:16:03 +0000 Subject: [PATCH] New man page. This will need modifications RSN. --- share/man/man8/picobsd.8 | 282 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 share/man/man8/picobsd.8 diff --git a/share/man/man8/picobsd.8 b/share/man/man8/picobsd.8 new file mode 100644 index 000000000000..11c1741b1936 --- /dev/null +++ b/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 . Man page and Makefiles created by Greg +Lehey . +.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 .