freebsd-skq/share/man/man8/picobsd.8

.\" -*- nroff-fill -*-
.\" $FreeBSD$
.Dd June 20, 2001
.Os
.Dt PICOBSD 8
.Sh NAME
.Nm picobsd
.Nd floppy disk based FreeBSD system
.Sh SYNOPSIS
.Nm
.Op options
.Op Ar floppy-type Op Ar site-name
.Sh DESCRIPTION
.Nm
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
.Nm picobsd
has been originally created to build simple standalone systems
such as firewalls or bridges, but because of the ability to
cross-build images with different source trees than the one
in the server, it can be extremely useful to developers to
test their code without having to reinstall the system.
.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 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 "xxxxxx" -compact
.It Fl -src Ar SRC_PATH
Use the source tree at
.Ar SRC_PATH
instead the one at
.Ar /usr/src .
Can be useful for cross-building floppy images.
When using this option, you must also create initialize the subtree at
.Ar SRC_PATH/../usr
with the correct include files, libraries and tools (such as the
.Xr config 8
program) that are necessary for the cross-build (see the
.Fl -init
option below).
The source files are unmodified by the
.Nm picobsd
script. However the source tree is not completely readonly,
because
.Xr config 8
expects the kernel configuration file to be in one of
its subdirectories, and also the process of initializing the
.Ar usr
subtree touches some parts of the source tree (this is a bug
in the release build scripts which might go away with time).
.Pp
.It Fl -init
When used together with the
.Fl -src
option, it initializes the
.Ar SRC_PATH/../usr
subtree as necessary to subsequently build picobsd images.
.Pp
.It Fl -modules
Also build kernel modules. They are not stored on the floppy
image but are left available in the build directory.
.Pp
.It Fl n
Make the script non interactive. Do not show the initial menu, and
proceed in the build process without requiring user input.
.Pp
.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.
.Pp
.It Fl -all_in_mfs
Puts the entire content of the filesystem in the memory filesystem
image which is contained in the kernel. This is the default behaviour,
and is extremely useful as the kernel itself can be loaded using
.Xr etherboot
or
.Xr pxeboot
to have a fully functional system.
.Pp
.It Fl -no_all_in_mfs
Leaves files contained into the
.Ar floppy.tree
on the floppy image, so they can be loaded separately from the kernel
(and updated individually to customize the floppy image).
.Pp
.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.
.Pp
.It Fl c
.It Fl clean
Clean the product of previous builds.
.Xr etherboot
.El
.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
.Xr netstat 1 ,
and
.Nm vm ,
a cut-down version of
.Xr vmstat 8 .
.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 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.
Starting from
.Fx 4.3 ,
the supported build script is
.Pa /usr/src/release/picobsd/build/picobsd
which can be run from anywhere.
When run in interactive mode (the default without the
.Fl -n
option), the script will let you configure the various parameters
used to build the floppy image.
The following kinds of floppy are envisaged, and we try to keep them
functional and fitting in the 1.44MB floppy despite the unavoidable
increases in the size of the kernel and its applications:
.Bl -hang -width "install  "
.It bridge
is a configuration suitable for bridges, routers and firewalls
.El
.Pp
The following configurations are also present but for reference
only. Many of them are irrimediably out of date and no effort
is done to keep them in good shape:
.Bl -hang -width "install  "
.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
.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
some of the following files and directories. For more
information on how to construct these files, look at one
of the standard
.Nm picobsd
configurations as a reference.
.Pp
.Bl -tag -width "xxxxx" -compact
.It Pa PICOBSD
The kernel configuration file (required). This is a mostly standard
kernel configuration file, possibly stripped down by removing
unnecessary drivers and options to reduce the kernel's size.
.Pp
To be recognised as a
.Nm
kernel config file, the file must also contain the line
beginning with #PicoBSD below, and a matching MD_ROOT_SIZE
option:
.Pp
.Bd -literal -offset indent

#marker    def_sz  init   MFS_inodes    floppy_inodes
#PicoBSD   4200    init   8192          32768
options MD_ROOT_SIZE=4200      # same as def_sz
.Ed
.Pp
to inform the script on the size of the memory filesystem and
a few other information on how to build the image.
.Pp
.It Pa crunch.conf
crunchgen configuration (required). See the
.Xr crunchgen 1
manpage for the syntax.
.Pp
.It Pa config
shell variables, sourced by the
.Pa picobsd
script (optional). The most important variables here are
.Pa MY_DEVS
which should be set to the list of device which should be
created in the
.Pa /dev
directory of the image (it is really the argument passed to
.Pa MAKEDEV ,
so you can refer to that manpage for the names), and the
.Pa fd_size
which can override the default size (in kilobytes) of the image.
By default,
.Pa fd_size=1440
which produces an image suitable for a standard floppy.
.Pp
If you plan to store the image on a CDROM (e.g. using
the El Torito floppy emulation), you can set
.Pa fd_size=2880 .
Same if you are planning to dump the image onto a hard disk
(either in a partition or on the whole disk), in which case you
are not even restricted to use one of the standard floppy sizes.
Using a large image size per se does not waste RAM at runtime,
because only the files that are actually loaded from the image
contribute to the memory usage.
.Pp
.It Pa floppy.tree.exclude
files from the standard floppy tree which are not needed (optional).
.Pp
.It Pa floppy.tree/
local additions to the standard floppy tree (optional).
.Pp
.It Pa floppy.tree. Ns ${site}
same as above, site-specific (optional).
.El
.Pp
More information on the build process can be found in the
comments 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 SRC_PATH
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.
As an example, to cross-build the "bridge" floppy
using RELENG_4 sources, you can do the following:
.Bd -literal -offset indent
  cd <some_empty_directory>
  mkdir FOO
  (cd FOO; cvs -d <my_repository> co -r RELENG_4 src )
  picobsd --src FOO/src --init	# this is needed only once
  picobsd --src FOO/src -n -v bridge
.Ed
.Pp
If the build is successful, the directory
.Ar build_dir-bridge/
will contain a
.Ar kernel
that can be downloaded with
.Xr etherboot 8 ,
a floppy image called
.Ar picobsd.bin ,
plus the products of the compilation in other directories.
If you want to modify the source tree in
.Ar FOO/src ,
a new image can be produced by simply running
.Bd -literal -offset indent
  picobsd --src FOO/src -n -v bridge
.Ed
.Pp
whereas if the change affects include files or libraries
you first need to update them e.g. by running first
.Bd -literal -offset indent
  picobsd --src FOO/src --init  # this is needed only once
.Ed
.Pp
as you would normally do for any change of this kind.
.Pp
.Sh INSTALLING PicoBSD
.Pp
.Ss Floppy install
Historically,
.Nm
is run from a floppy disk, where it can be installed with a simple
.Bd -literal -offset indent
  dd if=picobsd.bin of=/dev/rfd0
.Ed
.Pp
and the floppy is ready to run.
.Pp
.Ss Hard disk install
The same process can be used to store the image on a hard disk
(entire volume or one of the slices):
.Bd -literal -offset indent
  dd if=picobsd.bin of=/dev/ad2
  dd if=picobsd.bin of=/dev/ad2s3
  dd if=picobsd.bin of=/dev/ad2 oseek=NN
.Ed
.Pp
The first form will install the image on the entire disk, and it
should work in the same way as from a floppy.
.Pp
The second form will install the
on slice number 3 (which should be large enough to store the
content of the image). However the process will only have success if the
partition does not contain a valid disklabel, otherwise the kernel will
likely prevent overwriting the label. In this case you can use the
third form, replacing NN with the actual start of the partition
(as you can tell from
.Nm fdisk
).
Note that after saving the image to the slice, it will not be
recognised yet, you have to use the disklabel command to
properly initialize the label (don't ask why!).
One way to do this is
.Bd -literal -offset indent
  disklabel -w ad0s2 auto
  disklabel -e ad0s2
.Ed
.Pp
and from the editor enter a line corresponding to the actual partition, e.g.
if the image has 2.88MB (5760 sectors) you need to enter the following
line for the partition:
.Bd -literal -offset indent
  a: 5760   0    4.2BSD   512   4096
.Ed
.Pp
At this point the partition is bootable.
Note that the image size can be smaller than the slice size
(indicated as partition c:).
.Pp
.Ss CDROM install
Another option is to put the image on a CDROM. Assuming your image
for disk type
.Pa foo
is in the directory
.Pa build_dir-foo
then you can produce a bootable El Torito image (and burn it) with the
following command:
.Bd -literal -offset indent
mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
    -o cd.img build_dir-foo
burncd -f /dev/acd0c -s 4 data cd.img fixate
.Ed
.Pp
Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
most likely will not work.
.Pp
.Ss Booting from the network
Yet another way to use
.Nm
is to boot the image off the network.
For this purpose you should use the uncompressed kernel which is
available as a byproduct of the compilation. Refer to the documentation
for network booting for more details, the
.Nm
kernel is bootable as a standard
.Fx
kernel.
.Pp
.Sh BOOTING PicoBSD
To boot
.Nm ,
insert the floppy and reset the machine.  The boot procedure is similar to the
standard
.Fx
boot.
Booting from a floppy is normally rather slow (in the order of 1-2
minutes), things are much faster if you store your image on
a hard disk, Compact Flash, or CDROM.
.Pp
You can also use
.Xr etherboot
to load the preloaded, uncompressed kernel image
which is a byproduct of the
.Nm
build.
In this case
the load time is a matter of a few seconds, even on a 10Mbit/s
ethernet.
.Pp
After booting,
.Nm
loads the root filesystem from memory file system, starts
.Pa /sbin/init ,
and passes control to a first startup script,
.Pa /etc/rc .
The latter populates the
.Pa /etc
and
.Pa /root
directories with the default files, then tries to identify the boot
device (floppy, hard disk partition) and possibly override the content
of the root filesystem with files read from the boot device.
This allows you to store local configuration on the same media.
After this phase the boot device is no longer used, unless the
user specifically does it.
.Pp
After this, control is transferred to a second script,
.Pa /etc/rc1 ,
(can be overridden from the boot device).
This one tries to associate a hostname to the system by using
the MAC address of the first ethernet interface as a key, and
.Pa /etc/hosts
as a lookup table.
Then control is passed to the main user configuration script,
.Pa /etc/rc.conf ,
which is supposed to override the value of a number of configuration
variables which have been pre-set in
.Pa /etc/rc.conf.defaults .
You can use the
.Pa $hostname
variable to create different configurations from the same file.
.Pa
After taking control back,
.Pa /etc/rc1 completes the initializations, and as part of this
it configures network interfaces and optionally calls the
firewall configuration script,
.Pa /etc/rc.firewall ,
where the user can store his own firewall configuration.
.Pp
Note that by default
.Nm
runs entirely off main memory, and has no swap space, unless you
explicitly request it.
The boot device is also not used anymore after
.Pa /etc/rc1
takes control, again unless you explicitly request it.
.Pp
.Pp
.Sh CONFIGURING a PicoBSD system
The operation of a
.Nm
system can be configured through a few files which are read at boot
time, very much like a standard
.Fx
system. There are, however, some minor differences to reduce the
number of files to store and/or customize, thus saving space.
Among the files to configure we have the following:
.Pp
.Bl -tag -width "xxxxx" -compact
.It Pa /etc/hosts
Traditionally, this file contains the IP-to-hostname mappings.
In addition to this, the PicoBSD version of this file also contains
a mapping between Ethernet (MAC) addresses and hostnames, as follows:
.Pp
.Bd -literal -offset indent
#ethertable     start of the ethernet->hostname mapping
# mac_address           hostname
# 00:12:34:56:78:9a     pinco
# 12:34:56:*            pallino
# *                     this-matches-all
.Ed
.Pp
where the line containing "#ethertable" marks the start of the table.
.Pp
If the MAC address is not found, the script will prompt you to
enter a hostname and IP address for the system, and these
informations will be stored in the
.Pa /etc/hosts
file (in memory) so you can simply store them on disk later.
.Pp
Note that you can use wildcards in the address part, so a line
like the last one in the example will match any MAC address and
avoid the request.
.Et
.Pp
.It Pa /etc/rc.conf
This file contains a number of variables which control the
operation of the system, such as interface configuration,
router setup, network service startup, etc. .
For the exact list and meaning of these variables see
.Pa /etc/rc.conf.defaults .
.Pp
It is worth mentioning that some of the variables let you
overwrite the content of some files in
.Pa /etc .
This option is available at the moment for
.Pa /etc/host.conf
and
.Pa /etc/resolv.conf
whose content is generally very short and suitable for this
type of updating.
In case you use these variables, remember to use newlines
as appropriate, e.g.
.Pp
.Bd -literal -offset indent
host_conf="# this goes into /etc/host.conf
hosts
bind"
.Ed
.Pp
Although not mandatory in this file you should only set the
variables indicated in
.Pa /etc/rc.conf.defaults ,
and avoid starting services which depend on having the network running.
This can be done at a later time: if you set
.Pa firewall_enable="YES" ,
the
.Pa /etc/rc.firewall
script will be run after configuring the network interfaces,
so you can set up your firewall and safely start network services or enable
things such as routing and bridging.
.Et
.Pp
.It Pa /etc/rc.firewall
This script can be used to configure the
.Nm ipfw
firewall.
On entry, the
.Pa $fwcmd
variable is set to the pathname of the firewall command,
.Pa $firewall_type
contains the value set in
.Pa /etc/rc.conf ,
and
.Pa $hostname
contains the name assigned to the host.
.El
.Pp
There is a small script called
.Nm update
which can be used to edit and/or save to disk a copy of the files
that you have modified after booting.
The script takes one or more absolute pathnames, runs the
editor on the files passed as arguments, and then saves a
compressed copy of the files on the disk (mounting and
unmounting the latter around the operation).
.Pp
If invoked without arguments,
.Nm update
edits and saves
.Pa rc.conf
.Pa rc.firewall
and
.Pa master.passwd .
.Pp
If one of the arguments is
.Pa /etc
(the directory name alone),
then the command saves to disk (without editing)
all the files in the directory for which a copy
already exists on disk (e.g. as a result of a previous update).
.Pp
.Sh SEE ALSO
.Xr crunchgen 1 ,
.Xr swapon 8 ,
.Xr vnconfig 8
.Sh AUTHORS
.An -nosplit
.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
.Nm ,
the kernel of the system on which it is built must have the
.Xr vn 4
driver installed.
.Pp
The build process must be run as
.Dq root
because of the need of running
.Xr vnconfig 8
and
.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.