mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-28 20:55:21 +00:00
Update the manpage to reflect reality (and what was already in -stable).
This commit is contained in:
Luigi Rizzo
parent
d4140ab80c
commit
523c249f97
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=78498
|
|
@ -1,37 +1,74 @@
|
|||
.\" -*- nroff-fill -*-
|
||||
.\" $FreeBSD$
|
||||
.Dd December 23, 1999
|
||||
.Os FreeBSD
|
||||
.Dd June 20, 2001
|
||||
.Os
|
||||
.Dt PICOBSD 8
|
||||
.Sh NAME
|
||||
.Nm PicoBSD
|
||||
.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.
|
||||
.Op options
|
||||
.Op Ar floppy-type Op Ar site-name
|
||||
.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
|
||||
is a script which can be used to produce a minimal implementation of
|
||||
.Fx
|
||||
(historically called
|
||||
.Nm PicoBSD )
|
||||
which typically fits on one floppy disk, or can be downloaded as a
|
||||
single image file from some media such as CDROM, flash memory, or through
|
||||
.Xr etherboot .
|
||||
.Pp
|
||||
The boot media (typically a floppy disk) contains a boot loader and a
|
||||
compressed kernel which includes a memory file system.
|
||||
Depending on the media, it might also contain a number of
|
||||
additional files, which can be updated at run time, and are
|
||||
used to override/update those in the memory file system.
|
||||
.Pp
|
||||
The system loads the kernel in the normal way, uncompresses
|
||||
the memory file system and mounts it as root.
|
||||
It then updates the memory
|
||||
filesystem with files from the boot media (if present),
|
||||
and executes a specialized version of
|
||||
.Pa /etc/rc .
|
||||
The standard version of
|
||||
.Pa /etc/rc
|
||||
prompts for additional floppies and reads them in to the MFS file system.
|
||||
The boot media (floppy etc.) is
|
||||
required for loading only, and typically used as readonly.
|
||||
After the boot phase, the system runs entirely from ram.
|
||||
.Pp
|
||||
The following options are available (but also check the
|
||||
.Nm
|
||||
script for more details):
|
||||
.Pp
|
||||
.Bl -tag -width "--floppy_size" -compact
|
||||
.It Fl c
|
||||
.It Fl clean
|
||||
Clean the product of previous builds.
|
||||
.It Fl n
|
||||
Make the script non interactive. Do not show the initial menu, and
|
||||
proceed in the build process without requiring user input.
|
||||
.It Fl v
|
||||
Make the script verbose, showing the various commands to execute and
|
||||
waiting for user input before each of them. Useful when debugging.
|
||||
.It Fl -floppy_size Ar size
|
||||
Set the size of the floppy image. Values other than 1440 can
|
||||
be used for images that are burned into a CDROM, or downloaded
|
||||
using
|
||||
.Xr etherboot
|
||||
.It Fl -src Ar pathname
|
||||
Use the source tree at
|
||||
.Ar pathname
|
||||
instead the one at
|
||||
.Ar /usr/src .
|
||||
Can be useful for cross-building floppy images, but you must be
|
||||
careful in that there are dependencies with the
|
||||
.Xr config 8
|
||||
program, and also with include files and libraries.
|
||||
.El
|
||||
.Pp
|
||||
.Sh ENVIRONMENT
|
||||
As a result of the extreme size limitations, the
|
||||
.Nm
|
||||
.Nm
|
||||
environment differs from the normal
|
||||
.Fx
|
||||
in a number of ways:
|
||||
|
|
@ -48,13 +85,13 @@ floppy are joined together as a single executable built with
|
|||
Some programs are supplied in minimalistic versions, specifically
|
||||
.Nm ns ,
|
||||
a cut-down version of
|
||||
.Nm netstat ,
|
||||
.Xr netstat 1 ,
|
||||
and
|
||||
.Nm vm ,
|
||||
a cut-down version of
|
||||
.Nm vmstat .
|
||||
.Xr vmstat 8 .
|
||||
.El
|
||||
.Sh BUILDING PicoBSD
|
||||
.Sh BUILDING picobsd
|
||||
The
|
||||
.Nm
|
||||
sources reside in the hierarchy
|
||||
|
|
@ -62,20 +99,21 @@ sources reside in the hierarchy
|
|||
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
|
||||
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
|
||||
.Fx 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 -width "install "
|
||||
.It bridge
|
||||
is a configuration suitable for bridges, routers and firewalls
|
||||
.It dial
|
||||
is a configuration suitable for dial-out (ppp) networking.
|
||||
.It install
|
||||
|
|
@ -88,99 +126,50 @@ is a configuration suitable for general networking.
|
|||
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 .
|
||||
.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 Pa PICOBSD
|
||||
the kernel configuration file (required).
|
||||
.It Pa crunch.conf
|
||||
crunchgen configuration (required).
|
||||
.It Pa config
|
||||
shell variables, sourced by the
|
||||
.Pa picobsd
|
||||
script (optional).
|
||||
.It Pa floppy.tree.exclude
|
||||
files from the standard floppy tree which are not needed (optional).
|
||||
.It Pa floppy.tree/
|
||||
local additions to the standard floppy tree (optional).
|
||||
.It Pa floppy.tree. Ns ${site}
|
||||
same as above, site-specific (optional).
|
||||
.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 ,
|
||||
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
|
||||
More information on the build process can be found in the
|
||||
.Pa picobsd
|
||||
script.
|
||||
Sample configurations can be found in
|
||||
.Pa /usr/src/release/picobsd/ Ns ${type} Ns /
|
||||
.Sh USING ALTERNATE SOURCE TREES
|
||||
The build script can be instructed use an alternate source tree
|
||||
using the
|
||||
.Fl -src Ar pathname
|
||||
option.
|
||||
The tree that you specify must contain full sources for the kernel
|
||||
and for all programs that you want to include in your image.
|
||||
This option must be used with great care though, because different
|
||||
source trees might refer to different include files, libraries
|
||||
or versions of the
|
||||
.Xr config 8
|
||||
program.
|
||||
.Pp
|
||||
.Sh BOOTING PicoBSD
|
||||
To boot
|
||||
.Nm ,
|
||||
|
|
@ -188,32 +177,22 @@ 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.
|
||||
(BIOS Power On Self Test) until the system is up and running takes
|
||||
anywhere between 1 and 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
|
||||
To speed up booting, you can use
|
||||
.Xr etherboot
|
||||
to load the preloaded, uncompressed kernel image
|
||||
which is a byproduct of the
|
||||
.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.
|
||||
build.
|
||||
In this case
|
||||
the load time is a matter of a few seconds, even on a 10Mbit/s
|
||||
ethernet.
|
||||
.Ss Swap space
|
||||
After booting,
|
||||
.Nm
|
||||
runs entirely from the MFS file system. The floppies are no longer used, and
|
||||
runs entirely from the memory 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,
|
||||
|
|
@ -225,69 +204,35 @@ partition does not contain a dump you want to keep, you can use this swap with
|
|||
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 -nosplit
|
||||
.An Andrzej Bialecki Aq abial@FreeBSD.org .
|
||||
Man page and Makefiles created by
|
||||
.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
|
||||
.Pa Makefiles
|
||||
created by
|
||||
.An Greg Lehey Aq grog@lemis.com .
|
||||
.Sh BUGS
|
||||
In order to build
|
||||
In order to build
|
||||
.Nm ,
|
||||
the kernel of the system on which it is built must have the
|
||||
.Nm vn
|
||||
driver installed.
|
||||
.Xr vn 4
|
||||
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
|
||||
.Dq root
|
||||
because of the need of running
|
||||
.Xr vnconfig 8
|
||||
and
|
||||
.Pa /dev/vn1 .
|
||||
If these files are not in use by other programs, unexpected behaviour may
|
||||
result.
|
||||
.Xr mount 8 .
|
||||
.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 .
|
||||
|
|
|
|||
Loading…
Reference in a new issue