3.Dd March 9, 2002
4.Os
5.Dt PICOBSD 8
6.Sh NAME
7.Nm picobsd
8.Nd floppy disk based FreeBSD system
9.Sh SYNOPSIS
10.Nm
11.Op Ar options
12.Op Ar floppy-type Op Ar site-name
13.Sh DESCRIPTION
14The
15.Nm
16utility is a script which produces a minimal implementation of
17.Fx
18(historically called
19.Nm PicoBSD )
20which typically fits on one floppy disk, or can be downloaded as a
21single image file from some media such as CDROM, flash memory, or through
22.Xr etherboot .
23.Pp
24The
25.Nm
26utility was originally created to build simple standalone systems
27such as firewalls or bridges, but because of the ability to
28cross-build images with different source trees than the one
29in the server, it can be extremely useful to developers to
30test their code without having to reinstall the system.
31.Pp
32The boot media (typically a floppy disk) contains a boot loader and a
33compressed kernel which includes a memory file system.
34Depending on the media, it might also contain a number of
35additional files, which can be updated at run time, and are
36used to override/update those in the memory file system.
37.Pp
38The system loads the kernel in the normal way, uncompresses
39the memory file system and mounts it as root.
40It then updates the memory
41file system with files from the boot media (if present),
42and executes a specialized version of
43.Pa /etc/rc .
44The boot media (floppy, etc.) is
45required for loading only, and typically used read-only.
46After the boot phase, the system runs entirely from RAM.
47.Pp
48The following options are available (but also check the
49.Nm
50script for more details):
51.Pp
52.Bl -tag -width indent
53.It Fl -src Ar SRC_PATH
54Use the source tree at
55.Ar SRC_PATH
56instead the one at
57.Pa /usr/src .
58This can be useful for cross-building floppy images.
59When using this option, you must also create and initialize the subtree at
60.Ao Ar SRC_PATH Ac Ns Pa /../usr
61with the correct header files, libraries, and tools (such as the
62.Xr config 8
63program) that are necessary for the cross-build (see the
64.Fl -init
65option below).
66The source files are unmodified by the
67.Nm
68script.
69However the source tree is not completely read-only,
70because
71.Xr config 8
72expects the kernel configuration file to be in one of
73its subdirectories, and also the process of initializing the
74.Pa usr
75subtree touches some parts of the source tree (this is a bug
76in the release build scripts which might go away with time).
77.It Fl -init
78When used together with the
79.Fl -src
80option, this initializes the
81.Ao Ar SRC_PATH Ac Ns Pa /../usr
82subtree as necessary to subsequently build
83.Nm
84images.
85.It Fl -modules
86Also build kernel modules.
87These are not stored on the floppy
88image but are left available in the build directory.
89.It Fl n
90Make the script non-interactive.
91Do not show the initial menu, and
92proceed to the build process without requiring user input.
93.It Fl v
94Make the script verbose, showing
95commands to be executed and waiting for user
96input before executing each of them.
97Useful for debugging.
98.It Fl -all_in_mfs
99Put the entire contents of the file system in the
100memory file system image which is contained in the
101kernel.
102This is the default behaviour, and is
103extremely useful as the kernel itself can be loaded,
104using
105.Xr etherboot
106or
107.Xr pxeboot 8 ,
108as a fully functional system.
109.It Fl -no_all_in_mfs
110Leaves files contained in the
111.Pa floppy.tree
112on the floppy image, so they can be loaded separately
113from the kernel (and updated individually to
114customize the floppy image).
115.It Fl -floppy_size Ar size
116Set the size of the floppy image.
117Values other
118than 1440 can be used for images that are burned
119into a CDROM.
120.It Fl c , clean
121Clean the product of previous builds.
122.El
123.Sh ENVIRONMENT
124As a result of extreme size limitations, the
125.Nm
126environment differs from the normal
127.Fx
128in a number of ways:
129.Bl -bullet
130.It
131There are no dynamic libraries, and there is no directory
132.Pa /usr/lib .
133As a result, only static executables may be executed.
134.It
135In order to reduce the size of the executables, all executables on a specific
136floppy are joined together as a single executable built with
137.Xr crunchgen 1 .
138.It
139Some programs are supplied in minimalistic versions, specifically
140.Nm ns ,
141a cut-down version of
142.Xr netstat 1 ,
143and
144.Nm vm ,
145a cut-down version of
146.Xr vmstat 8 .
147.El
148.Sh BUILDING PicoBSD
149The
150.Nm
151sources reside in the hierarchy
152.Pa /usr/src/release/picobsd .
153In the following discussion, all relative path names are relative to this
154directory.
155The
156.Nm
157build process has changed slightly over time, in order to cope
158with the unavoidable increase of code size, which requires more and more
159tricks to cram as much as possible onto the floppies.
160Starting from
161.Fx 4.3 ,
162the supported build script is
163.Pa /usr/src/release/picobsd/build/picobsd
164which can be run from anywhere.
165When run in interactive mode (the default without the
166.Fl -n
167option), the script will let you configure the various parameters
168used to build the floppy image.
169The following kinds of floppy are envisaged, and we try to keep them
170functional and fitting in the 1.44MB floppy despite the unavoidable
171increases in the size of the kernel and its applications:
172.Bl -hang -width ".Pa bridge"
173.It Pa bridge
174configuration suitable for bridges, routers and firewalls.
175.El
176.Pp
177The following configurations are also present but for reference
178only.
179Many of them are irremediably out of date and no effort
180is done to keep them in good shape:
181.Bl -hang -width ".Pa bridge"
182.It Pa dial
183configuration suitable for dial-out
184.Pq Xr ppp 8
185networking.
186.It Pa isp
187configuration suitable for dial-in
188.Pq Xr ppp 8
189networking.
190.It Pa net
191configuration suitable for general networking.
192.It Pa router
193configuration suitable for use as a router.
194This particular configuration
195aims to work on minimal hardware.
196.El
197.Pp
198These configurations serve only as examples for
199your own modification.
200Not all of them have been tested,
201and you might need small tweaks to the configuration
202files to make them work or even fit into the
203available disk space as code size increases.
204.Pp
205You can define your own floppy type, by creating a directory
206with a name of your choice (e.g.\&
207.Pa FOO )
208which contains
209some of the following files and directories.
210For more
211information on how to construct these files, look at one
212of the standard
213.Nm
214configurations as a reference.
215.Bl -tag -width indent
216.It Pa PICOBSD
217The kernel configuration file (required).
218This is a mostly standard
219kernel configuration file, possibly stripped down by removing
220unnecessary drivers and options to reduce the kernel's size.
221.Pp
222To be recognised as a
223.Nm
224kernel config file, the file must also contain the line
225beginning with
226.Dq Li #PicoBSD
227below, and a matching
228.Dv MD_ROOT_SIZE
229option:
230.Bd -literal -offset indent
231#marker def_sz init MFS_inodes floppy_inodes
232#PicoBSD 4200 init 8192 32768
233options MD_ROOT_SIZE=4200 # same as def_sz
234.Ed
235.Pp
236This informs the script of the size of the memory file system and
237provides a few other details on how to build the image.
238.It Pa crunch.conf
239.Xr crunchgen 1
240configuration (required).
241It contains the list of directories containing program sources,
242the list of binaries to be built, and the list of libraries that
243these programs use.
244See the
245.Xr crunchgen 1
246manpage for the exact details on the syntax of this file.
247.Pp
248The following issues are particularly important when dealing
249with
250.Nm
251configurations:
252.Bl -bullet
253.It
254We can pass build options to those makefiles which understand
255that, in order to reduce the size of the programs.
256This is achieved with a line of the form
257.Pp
| 3.Dd March 9, 2002
4.Os
5.Dt PICOBSD 8
6.Sh NAME
7.Nm picobsd
8.Nd floppy disk based FreeBSD system
9.Sh SYNOPSIS
10.Nm
11.Op Ar options
12.Op Ar floppy-type Op Ar site-name
13.Sh DESCRIPTION
14The
15.Nm
16utility is a script which produces a minimal implementation of
17.Fx
18(historically called
19.Nm PicoBSD )
20which typically fits on one floppy disk, or can be downloaded as a
21single image file from some media such as CDROM, flash memory, or through
22.Xr etherboot .
23.Pp
24The
25.Nm
26utility was originally created to build simple standalone systems
27such as firewalls or bridges, but because of the ability to
28cross-build images with different source trees than the one
29in the server, it can be extremely useful to developers to
30test their code without having to reinstall the system.
31.Pp
32The boot media (typically a floppy disk) contains a boot loader and a
33compressed kernel which includes a memory file system.
34Depending on the media, it might also contain a number of
35additional files, which can be updated at run time, and are
36used to override/update those in the memory file system.
37.Pp
38The system loads the kernel in the normal way, uncompresses
39the memory file system and mounts it as root.
40It then updates the memory
41file system with files from the boot media (if present),
42and executes a specialized version of
43.Pa /etc/rc .
44The boot media (floppy, etc.) is
45required for loading only, and typically used read-only.
46After the boot phase, the system runs entirely from RAM.
47.Pp
48The following options are available (but also check the
49.Nm
50script for more details):
51.Pp
52.Bl -tag -width indent
53.It Fl -src Ar SRC_PATH
54Use the source tree at
55.Ar SRC_PATH
56instead the one at
57.Pa /usr/src .
58This can be useful for cross-building floppy images.
59When using this option, you must also create and initialize the subtree at
60.Ao Ar SRC_PATH Ac Ns Pa /../usr
61with the correct header files, libraries, and tools (such as the
62.Xr config 8
63program) that are necessary for the cross-build (see the
64.Fl -init
65option below).
66The source files are unmodified by the
67.Nm
68script.
69However the source tree is not completely read-only,
70because
71.Xr config 8
72expects the kernel configuration file to be in one of
73its subdirectories, and also the process of initializing the
74.Pa usr
75subtree touches some parts of the source tree (this is a bug
76in the release build scripts which might go away with time).
77.It Fl -init
78When used together with the
79.Fl -src
80option, this initializes the
81.Ao Ar SRC_PATH Ac Ns Pa /../usr
82subtree as necessary to subsequently build
83.Nm
84images.
85.It Fl -modules
86Also build kernel modules.
87These are not stored on the floppy
88image but are left available in the build directory.
89.It Fl n
90Make the script non-interactive.
91Do not show the initial menu, and
92proceed to the build process without requiring user input.
93.It Fl v
94Make the script verbose, showing
95commands to be executed and waiting for user
96input before executing each of them.
97Useful for debugging.
98.It Fl -all_in_mfs
99Put the entire contents of the file system in the
100memory file system image which is contained in the
101kernel.
102This is the default behaviour, and is
103extremely useful as the kernel itself can be loaded,
104using
105.Xr etherboot
106or
107.Xr pxeboot 8 ,
108as a fully functional system.
109.It Fl -no_all_in_mfs
110Leaves files contained in the
111.Pa floppy.tree
112on the floppy image, so they can be loaded separately
113from the kernel (and updated individually to
114customize the floppy image).
115.It Fl -floppy_size Ar size
116Set the size of the floppy image.
117Values other
118than 1440 can be used for images that are burned
119into a CDROM.
120.It Fl c , clean
121Clean the product of previous builds.
122.El
123.Sh ENVIRONMENT
124As a result of extreme size limitations, the
125.Nm
126environment differs from the normal
127.Fx
128in a number of ways:
129.Bl -bullet
130.It
131There are no dynamic libraries, and there is no directory
132.Pa /usr/lib .
133As a result, only static executables may be executed.
134.It
135In order to reduce the size of the executables, all executables on a specific
136floppy are joined together as a single executable built with
137.Xr crunchgen 1 .
138.It
139Some programs are supplied in minimalistic versions, specifically
140.Nm ns ,
141a cut-down version of
142.Xr netstat 1 ,
143and
144.Nm vm ,
145a cut-down version of
146.Xr vmstat 8 .
147.El
148.Sh BUILDING PicoBSD
149The
150.Nm
151sources reside in the hierarchy
152.Pa /usr/src/release/picobsd .
153In the following discussion, all relative path names are relative to this
154directory.
155The
156.Nm
157build process has changed slightly over time, in order to cope
158with the unavoidable increase of code size, which requires more and more
159tricks to cram as much as possible onto the floppies.
160Starting from
161.Fx 4.3 ,
162the supported build script is
163.Pa /usr/src/release/picobsd/build/picobsd
164which can be run from anywhere.
165When run in interactive mode (the default without the
166.Fl -n
167option), the script will let you configure the various parameters
168used to build the floppy image.
169The following kinds of floppy are envisaged, and we try to keep them
170functional and fitting in the 1.44MB floppy despite the unavoidable
171increases in the size of the kernel and its applications:
172.Bl -hang -width ".Pa bridge"
173.It Pa bridge
174configuration suitable for bridges, routers and firewalls.
175.El
176.Pp
177The following configurations are also present but for reference
178only.
179Many of them are irremediably out of date and no effort
180is done to keep them in good shape:
181.Bl -hang -width ".Pa bridge"
182.It Pa dial
183configuration suitable for dial-out
184.Pq Xr ppp 8
185networking.
186.It Pa isp
187configuration suitable for dial-in
188.Pq Xr ppp 8
189networking.
190.It Pa net
191configuration suitable for general networking.
192.It Pa router
193configuration suitable for use as a router.
194This particular configuration
195aims to work on minimal hardware.
196.El
197.Pp
198These configurations serve only as examples for
199your own modification.
200Not all of them have been tested,
201and you might need small tweaks to the configuration
202files to make them work or even fit into the
203available disk space as code size increases.
204.Pp
205You can define your own floppy type, by creating a directory
206with a name of your choice (e.g.\&
207.Pa FOO )
208which contains
209some of the following files and directories.
210For more
211information on how to construct these files, look at one
212of the standard
213.Nm
214configurations as a reference.
215.Bl -tag -width indent
216.It Pa PICOBSD
217The kernel configuration file (required).
218This is a mostly standard
219kernel configuration file, possibly stripped down by removing
220unnecessary drivers and options to reduce the kernel's size.
221.Pp
222To be recognised as a
223.Nm
224kernel config file, the file must also contain the line
225beginning with
226.Dq Li #PicoBSD
227below, and a matching
228.Dv MD_ROOT_SIZE
229option:
230.Bd -literal -offset indent
231#marker def_sz init MFS_inodes floppy_inodes
232#PicoBSD 4200 init 8192 32768
233options MD_ROOT_SIZE=4200 # same as def_sz
234.Ed
235.Pp
236This informs the script of the size of the memory file system and
237provides a few other details on how to build the image.
238.It Pa crunch.conf
239.Xr crunchgen 1
240configuration (required).
241It contains the list of directories containing program sources,
242the list of binaries to be built, and the list of libraries that
243these programs use.
244See the
245.Xr crunchgen 1
246manpage for the exact details on the syntax of this file.
247.Pp
248The following issues are particularly important when dealing
249with
250.Nm
251configurations:
252.Bl -bullet
253.It
254We can pass build options to those makefiles which understand
255that, in order to reduce the size of the programs.
256This is achieved with a line of the form
257.Pp
|
259.It
260When providing the list of directories where source files are, it
261is convenient to list the following entry first:
262.Pp
263.Dl "srcdirs /usr/src/release/picobsd/tinyware"
264.Pp
265so that
266.Nm Ns -specific
267versions of the programs will be found there.
268.It
269The string
270.Dq Li @__CWD__@
271is replaced with the full pathname of the directory where the
272.Nm
273configuration resides (i.e., the one where we find
274.Pa PICOBSD , crunch.conf ,
275and so on).
276This can be useful to refer source code that resides within a
277configuration, e.g.\&
278.Pp
279.Dl "srcdirs @__CWD__@/src"
280.El
281.It Pa config
282Shell variables, sourced by the
283.Nm
284script (optional).
285The most important variables here are:
286.Bl -tag -width ".Va MY_DEVS"
287.It Va MY_DEVS
288(Not used in
289.Fx 5.0
290where we have
291.Xr devfs 5 ) .
292Should be set to the list of devices to be created in the
293.Pa /dev
294directory of the image (it is really the argument passed to
295.Xr MAKEDEV 8 ,
296so refer to that manpage for the names).
297.It Va fd_size
298Size (in kilobytes) of the
299.Nm
300image.
301By default,
302.Va fd_size
303is set to 1440
304which produces an image suitable for a standard floppy.
305.Pp
306If you plan to store the image on a CDROM (e.g.\& using
307the
308.Dq "El Torito"
309floppy emulation), you can set
310.Va fd_size
311equal to 2880.
312If you are planning to dump the image onto a hard disk
313(either in a partition or on the whole disk), you
314are not restricted to one of the standard floppy sizes.
315Using a large image size per se does not waste RAM at runtime,
316because only the files that are actually loaded from the image
317contribute to the memory usage.
318.It Va import_files
319Contains a list of files to be imported in the floppy tree.
320Absolute names refer to the standard file system, relative
321names refer to the root of the source tree being used
322(i.e.\&
323.Va SRC_PATH/.. ) .
324You can normally use this option if you want to import
325files such as shared libraries, or databases, without
326having to replicate them first in your configuration
327under the
328.Pa floppy.tree/
329directory.
330.El
331.It Pa floppy.tree.exclude
332List of files from the standard floppy tree which
333we do not want to be copied (optional).
334.It Pa floppy.tree/
335Local additions to the standard floppy tree (optional).
336The content of this subtree will be copied as-is into the
337floppy image.
338.It Pa floppy.tree. Ns Aq Ar site-name
339Same as above, but site-specific (optional).
340.El
341.Pp
342More information on the build process can be found in the
343comments in the
344.Nm
345script.
346Sample configurations can be found in
347.Pa /usr/src/release/picobsd/ Ns Ao Ar floppy-type Ac Ns Pa /
348.Sh USING ALTERNATE SOURCE TREES
349The build script can be instructed to use an alternate source tree
350using the
351.Fl -src Ar SRC_PATH
352option.
353The tree that you specify must contain full sources for the kernel
354and for all programs that you want to include in your image.
355As an example, to cross-build the
356.Pa bridge
357floppy
358using RELENG_4 sources, you can do the following:
359.Bd -literal -offset indent
360cd <some_empty_directory>
361mkdir FOO
362(cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
363picobsd --src FOO/src --init # this is needed only once
364picobsd --src FOO/src -n -v bridge
365.Ed
366.Pp
367If the build is successful, the directory
368.Pa build_dir-bridge/
369will contain a
370.Pa kernel
371that can be downloaded with
372.Xr etherboot ,
373a floppy image called
374.Pa picobsd.bin ,
375plus the products of the compilation in other directories.
376If you want to modify the source tree in
377.Pa FOO/src ,
378a new image can be produced by simply running
379.Pp
380.Dl "picobsd --src FOO/src -n -v bridge"
381.Pp
382whereas if the change affects include files or libraries
383you first need to update them, e.g.\& by running first
384.Pp
385.Dl "picobsd --src FOO/src --init # this is needed only once"
386.Pp
387as you would normally do for any change of this kind.
388.Sh INSTALLING PicoBSD
389.Ss Floppy Install
390Historically,
391.Nm
392is run from a floppy disk, where it can be installed with a simple
393.Pp
394.Dl "dd if=picobsd.bin of=/dev/rfd0"
395.Pp
396and the floppy is ready to boot.
397.Ss Hard Disk Install
398The same process can be used to store the image on a hard disk
399(entire volume or one of the slices):
400.Bd -literal -offset indent
401dd if=picobsd.bin of=/dev/ad2
402dd if=picobsd.bin of=/dev/ad2s3
403dd if=picobsd.bin of=/dev/ad2 oseek=NN
404.Ed
405.Pp
406The first form will install the image on the entire disk, and it
407should work in the same way as for a floppy.
408.Pp
409The second form will install the image
410on slice number 3 (which should be large enough to store the
411contents of the image).
412However, the process will only have success if the
413partition does not contain a valid disklabel, otherwise the kernel will
414likely prevent overwriting the label.
415In this case you can use the
416third form, replacing
417.Ar NN
418with the actual start of the partition
419(which you can determine using
420.Xr fdisk 8 ) .
421Note that after saving the image to the slice, it will not yet be
422recognised.
423You have to use the
424.Xr disklabel 8
425command to properly initialize the label (do not ask why!).
426One way to do this is
427.Bd -literal -offset indent
428disklabel -w ad0s2 auto
429disklabel -e ad0s2
430.Ed
431.Pp
432and from the editor enter a line corresponding to the actual partition, e.g.\&
433if the image has 2.88MB (5760 sectors) you need to enter the following
434line for the partition:
435.Pp
436.Dl "a: 5760 0 4.2BSD 512 4096"
437.Pp
438At this point the partition is bootable.
439Note that the image size can be smaller than the slice size
440(indicated as partition
441.Dq Li c: ) .
442.Ss CDROM Install
443Another option is to put the image on a CDROM.
444Assuming your image
445for disk type
446.Pa foo
447is in the directory
448.Pa build_dir-foo
449then you can produce a bootable
450.Dq "El Torito"
451image (and burn it) with the
452following command:
453.Bd -literal -offset indent
454mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
455 -o cd.img build_dir-foo
456burncd -f /dev/acd0c -s 4 data cd.img fixate
457.Ed
458.Pp
459Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
460most likely will not work.
461.Ss Booting From The Network
462Yet another way to use
463.Nm
464is to boot the image off the network.
465For this purpose you should use the uncompressed kernel which is
466available as a byproduct of the compilation.
467Refer to the documentation
468for network booting for more details, the
469.Nm
470kernel is bootable as a standard
471.Fx
472kernel.
473.Sh BOOTING PicoBSD
474To boot
475.Nm ,
476insert the floppy and reset the machine.
477The boot procedure is similar to the
478standard
479.Fx
480boot.
481Booting from a floppy is normally rather slow (in the order of 1-2
482minutes), things are much faster if you store your image on
483a hard disk, Compact Flash, or CDROM.
484.Pp
485You can also use
486.Xr etherboot
487to load the preloaded, uncompressed kernel image
488which is a byproduct of the
489.Nm
490build.
491In this case
492the load time is a matter of a few seconds, even on a 10Mbit/s
493ethernet.
494.Pp
495After booting,
496.Nm
497loads the root file system from the memory file system, starts
498.Pa /sbin/init ,
499and passes control to a first startup script,
500.Pa /etc/rc .
501The latter populates the
502.Pa /etc
503and
504.Pa /root
505directories with the default files, then tries to identify the boot
506device (floppy, hard disk partition) and possibly override the contents
507of the root file system with files read from the boot device.
508This allows you to store local configuration on the same media.
509After this phase the boot device is no longer used, unless the
510user specifically does it.
511.Pp
512After this, control is transferred to a second script,
513.Pa /etc/rc1
514(which can be overridden from the boot device).
515This script tries to associate a hostname to the system by using
516the MAC address of the first ethernet interface as a key, and
517.Pa /etc/hosts
518as a lookup table.
519Then control is passed to the main user configuration script,
520.Pa /etc/rc.conf ,
521which is supposed to override the value of a number of configuration
522variables which have been pre-set in
523.Pa /etc/rc.conf.defaults .
524You can use the
525.Va hostname
526variable to create different configurations from the same file.
527After taking control back,
528.Pa /etc/rc1
529completes the initializations, and as part of this
530it configures network interfaces and optionally calls the
531firewall configuration script,
532.Pa /etc/rc.firewall ,
533where the user can store his own firewall configuration.
534.Pp
535Note that by default
536.Nm
537runs entirely from main memory, and has no swap space, unless you
538explicitly request it.
539The boot device is also not used anymore after
540.Pa /etc/rc1
541takes control, again, unless you explicitly request it.
542.Sh CONFIGURING a PicoBSD system
543The operation of a
544.Nm
545system can be configured through a few files which are read at boot
546time, very much like a standard
547.Fx
548system.
549There are, however, some minor differences to reduce the
550number of files to store and/or customize, thus saving space.
551Among the files to configure we have the following:
552.Bl -tag -width indent
553.It Pa /etc/hosts
554Traditionally, this file contains the IP-to-hostname mappings.
555In addition to this, the
556.Nm
557version of this file also contains
558a mapping between Ethernet (MAC) addresses and hostnames, as follows:
559.Bd -literal -offset indent
560#ethertable start of the ethernet->hostname mapping
561# mac_address hostname
562# 00:12:34:56:78:9a pinco
563# 12:34:56:* pallino
564# * this-matches-all
565.Ed
566.Pp
567where the line containing
568.Dq Li #ethertable
569marks the start of the table.
570.Pp
571If the MAC address is not found, the script will prompt you to
572enter a hostname and IP address for the system, and this
573information will be stored in the
574.Pa /etc/hosts
575file (in memory) so you can simply store them on disk later.
576.Pp
577Note that you can use wildcards in the address part, so a line
578like the last one in the example will match any MAC address and
579avoid the request.
580.It Pa /etc/rc.conf
581This file contains a number of variables which control the
582operation of the system, such as interface configuration,
583router setup, network service startup, etc.
584For the exact list and meaning of these variables see
585.Pa /etc/rc.conf.defaults .
586.Pp
587It is worth mentioning that some of the variables let you
588overwrite the contents of some files in
589.Pa /etc .
590This option is available at the moment for
591.Pa /etc/host.conf
592and
593.Pa /etc/resolv.conf ,
594whose contents are generally very short and suitable for this
595type of updating.
596In case you use these variables, remember to use newlines
597as appropriate, e.g.\&
598.Bd -literal -offset indent
599host_conf="# this goes into /etc/host.conf
600hosts
601bind"
602.Ed
603.Pp
604Although not mandatory, in this file you should only set the
605variables indicated in
606.Pa /etc/rc.conf.defaults ,
607and avoid starting services which depend on having the network running.
608This can be done at a later time: if you set
609.Va firewall_enable Ns = Ns Qq Li YES ,
610the
611.Pa /etc/rc.firewall
612script will be run after configuring the network interfaces,
613so you can set up your firewall and safely start network services or enable
614things such as routing and bridging.
615.It Pa /etc/rc.firewall
616This script can be used to configure the
617.Xr ipfw 4
618firewall.
619On entry, the
620.Va fwcmd
621variable is set to the pathname of the firewall command,
622.Va firewall_type
623contains the value set in
624.Pa /etc/rc.conf ,
625and
626.Va hostname
627contains the name assigned to the host.
628.El
629.Pp
630There is a small script called
631.Nm update
632which can be used to edit and/or save to disk a copy of the files
633you have modified after booting.
634The script takes one or more absolute pathnames, runs the
635editor on the files passed as arguments, and then saves a
636compressed copy of the files on the disk (mounting and
637unmounting the latter around the operation).
638.Pp
639If invoked without arguments,
640.Nm update
641edits and saves
642.Pa rc.conf , rc.firewall ,
643and
644.Pa master.passwd .
645.Pp
646If one of the arguments is
647.Pa /etc
648(the directory name alone),
649then the command saves to disk (without editing)
650all the files in the directory for which a copy
651already exists on disk (e.g.\& as a result of a previous update).
652.Sh SEE ALSO
653.Xr crunchgen 1 ,
654.Xr mdconfig 8 ,
655.Xr swapon 8 ,
656.Xr vnconfig 8
657.Sh AUTHORS
658.An -nosplit
659.An Andrzej Bialecki Aq abial@FreeBSD.org ,
660with subsequent work on the scripts by
661.An Luigi Rizzo Aq luigi@iet.unipi.it
662and others.
663Man page and
664.Pa Makefiles
665created by
666.An Greg Lehey Aq grog@lemis.com .
667.Sh BUGS
668In order to build
669.Nm ,
670the kernel of the system on which it is built must have the
671.Xr vn 4
672driver installed.
673.Pp
674The build process must be run as
675.Dq root
676because of the need of running
677.Xr mdconfig 8 Ns / Ns Xr vnconfig 8
678and
679.Xr mount 8 .
680.Pp
681Building
682.Nm
683is still a black art.
684The biggest problem is determining what will fit on the
685floppies, and the only practical method is trial and error.
| 259.It
260When providing the list of directories where source files are, it
261is convenient to list the following entry first:
262.Pp
263.Dl "srcdirs /usr/src/release/picobsd/tinyware"
264.Pp
265so that
266.Nm Ns -specific
267versions of the programs will be found there.
268.It
269The string
270.Dq Li @__CWD__@
271is replaced with the full pathname of the directory where the
272.Nm
273configuration resides (i.e., the one where we find
274.Pa PICOBSD , crunch.conf ,
275and so on).
276This can be useful to refer source code that resides within a
277configuration, e.g.\&
278.Pp
279.Dl "srcdirs @__CWD__@/src"
280.El
281.It Pa config
282Shell variables, sourced by the
283.Nm
284script (optional).
285The most important variables here are:
286.Bl -tag -width ".Va MY_DEVS"
287.It Va MY_DEVS
288(Not used in
289.Fx 5.0
290where we have
291.Xr devfs 5 ) .
292Should be set to the list of devices to be created in the
293.Pa /dev
294directory of the image (it is really the argument passed to
295.Xr MAKEDEV 8 ,
296so refer to that manpage for the names).
297.It Va fd_size
298Size (in kilobytes) of the
299.Nm
300image.
301By default,
302.Va fd_size
303is set to 1440
304which produces an image suitable for a standard floppy.
305.Pp
306If you plan to store the image on a CDROM (e.g.\& using
307the
308.Dq "El Torito"
309floppy emulation), you can set
310.Va fd_size
311equal to 2880.
312If you are planning to dump the image onto a hard disk
313(either in a partition or on the whole disk), you
314are not restricted to one of the standard floppy sizes.
315Using a large image size per se does not waste RAM at runtime,
316because only the files that are actually loaded from the image
317contribute to the memory usage.
318.It Va import_files
319Contains a list of files to be imported in the floppy tree.
320Absolute names refer to the standard file system, relative
321names refer to the root of the source tree being used
322(i.e.\&
323.Va SRC_PATH/.. ) .
324You can normally use this option if you want to import
325files such as shared libraries, or databases, without
326having to replicate them first in your configuration
327under the
328.Pa floppy.tree/
329directory.
330.El
331.It Pa floppy.tree.exclude
332List of files from the standard floppy tree which
333we do not want to be copied (optional).
334.It Pa floppy.tree/
335Local additions to the standard floppy tree (optional).
336The content of this subtree will be copied as-is into the
337floppy image.
338.It Pa floppy.tree. Ns Aq Ar site-name
339Same as above, but site-specific (optional).
340.El
341.Pp
342More information on the build process can be found in the
343comments in the
344.Nm
345script.
346Sample configurations can be found in
347.Pa /usr/src/release/picobsd/ Ns Ao Ar floppy-type Ac Ns Pa /
348.Sh USING ALTERNATE SOURCE TREES
349The build script can be instructed to use an alternate source tree
350using the
351.Fl -src Ar SRC_PATH
352option.
353The tree that you specify must contain full sources for the kernel
354and for all programs that you want to include in your image.
355As an example, to cross-build the
356.Pa bridge
357floppy
358using RELENG_4 sources, you can do the following:
359.Bd -literal -offset indent
360cd <some_empty_directory>
361mkdir FOO
362(cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
363picobsd --src FOO/src --init # this is needed only once
364picobsd --src FOO/src -n -v bridge
365.Ed
366.Pp
367If the build is successful, the directory
368.Pa build_dir-bridge/
369will contain a
370.Pa kernel
371that can be downloaded with
372.Xr etherboot ,
373a floppy image called
374.Pa picobsd.bin ,
375plus the products of the compilation in other directories.
376If you want to modify the source tree in
377.Pa FOO/src ,
378a new image can be produced by simply running
379.Pp
380.Dl "picobsd --src FOO/src -n -v bridge"
381.Pp
382whereas if the change affects include files or libraries
383you first need to update them, e.g.\& by running first
384.Pp
385.Dl "picobsd --src FOO/src --init # this is needed only once"
386.Pp
387as you would normally do for any change of this kind.
388.Sh INSTALLING PicoBSD
389.Ss Floppy Install
390Historically,
391.Nm
392is run from a floppy disk, where it can be installed with a simple
393.Pp
394.Dl "dd if=picobsd.bin of=/dev/rfd0"
395.Pp
396and the floppy is ready to boot.
397.Ss Hard Disk Install
398The same process can be used to store the image on a hard disk
399(entire volume or one of the slices):
400.Bd -literal -offset indent
401dd if=picobsd.bin of=/dev/ad2
402dd if=picobsd.bin of=/dev/ad2s3
403dd if=picobsd.bin of=/dev/ad2 oseek=NN
404.Ed
405.Pp
406The first form will install the image on the entire disk, and it
407should work in the same way as for a floppy.
408.Pp
409The second form will install the image
410on slice number 3 (which should be large enough to store the
411contents of the image).
412However, the process will only have success if the
413partition does not contain a valid disklabel, otherwise the kernel will
414likely prevent overwriting the label.
415In this case you can use the
416third form, replacing
417.Ar NN
418with the actual start of the partition
419(which you can determine using
420.Xr fdisk 8 ) .
421Note that after saving the image to the slice, it will not yet be
422recognised.
423You have to use the
424.Xr disklabel 8
425command to properly initialize the label (do not ask why!).
426One way to do this is
427.Bd -literal -offset indent
428disklabel -w ad0s2 auto
429disklabel -e ad0s2
430.Ed
431.Pp
432and from the editor enter a line corresponding to the actual partition, e.g.\&
433if the image has 2.88MB (5760 sectors) you need to enter the following
434line for the partition:
435.Pp
436.Dl "a: 5760 0 4.2BSD 512 4096"
437.Pp
438At this point the partition is bootable.
439Note that the image size can be smaller than the slice size
440(indicated as partition
441.Dq Li c: ) .
442.Ss CDROM Install
443Another option is to put the image on a CDROM.
444Assuming your image
445for disk type
446.Pa foo
447is in the directory
448.Pa build_dir-foo
449then you can produce a bootable
450.Dq "El Torito"
451image (and burn it) with the
452following command:
453.Bd -literal -offset indent
454mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
455 -o cd.img build_dir-foo
456burncd -f /dev/acd0c -s 4 data cd.img fixate
457.Ed
458.Pp
459Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
460most likely will not work.
461.Ss Booting From The Network
462Yet another way to use
463.Nm
464is to boot the image off the network.
465For this purpose you should use the uncompressed kernel which is
466available as a byproduct of the compilation.
467Refer to the documentation
468for network booting for more details, the
469.Nm
470kernel is bootable as a standard
471.Fx
472kernel.
473.Sh BOOTING PicoBSD
474To boot
475.Nm ,
476insert the floppy and reset the machine.
477The boot procedure is similar to the
478standard
479.Fx
480boot.
481Booting from a floppy is normally rather slow (in the order of 1-2
482minutes), things are much faster if you store your image on
483a hard disk, Compact Flash, or CDROM.
484.Pp
485You can also use
486.Xr etherboot
487to load the preloaded, uncompressed kernel image
488which is a byproduct of the
489.Nm
490build.
491In this case
492the load time is a matter of a few seconds, even on a 10Mbit/s
493ethernet.
494.Pp
495After booting,
496.Nm
497loads the root file system from the memory file system, starts
498.Pa /sbin/init ,
499and passes control to a first startup script,
500.Pa /etc/rc .
501The latter populates the
502.Pa /etc
503and
504.Pa /root
505directories with the default files, then tries to identify the boot
506device (floppy, hard disk partition) and possibly override the contents
507of the root file system with files read from the boot device.
508This allows you to store local configuration on the same media.
509After this phase the boot device is no longer used, unless the
510user specifically does it.
511.Pp
512After this, control is transferred to a second script,
513.Pa /etc/rc1
514(which can be overridden from the boot device).
515This script tries to associate a hostname to the system by using
516the MAC address of the first ethernet interface as a key, and
517.Pa /etc/hosts
518as a lookup table.
519Then control is passed to the main user configuration script,
520.Pa /etc/rc.conf ,
521which is supposed to override the value of a number of configuration
522variables which have been pre-set in
523.Pa /etc/rc.conf.defaults .
524You can use the
525.Va hostname
526variable to create different configurations from the same file.
527After taking control back,
528.Pa /etc/rc1
529completes the initializations, and as part of this
530it configures network interfaces and optionally calls the
531firewall configuration script,
532.Pa /etc/rc.firewall ,
533where the user can store his own firewall configuration.
534.Pp
535Note that by default
536.Nm
537runs entirely from main memory, and has no swap space, unless you
538explicitly request it.
539The boot device is also not used anymore after
540.Pa /etc/rc1
541takes control, again, unless you explicitly request it.
542.Sh CONFIGURING a PicoBSD system
543The operation of a
544.Nm
545system can be configured through a few files which are read at boot
546time, very much like a standard
547.Fx
548system.
549There are, however, some minor differences to reduce the
550number of files to store and/or customize, thus saving space.
551Among the files to configure we have the following:
552.Bl -tag -width indent
553.It Pa /etc/hosts
554Traditionally, this file contains the IP-to-hostname mappings.
555In addition to this, the
556.Nm
557version of this file also contains
558a mapping between Ethernet (MAC) addresses and hostnames, as follows:
559.Bd -literal -offset indent
560#ethertable start of the ethernet->hostname mapping
561# mac_address hostname
562# 00:12:34:56:78:9a pinco
563# 12:34:56:* pallino
564# * this-matches-all
565.Ed
566.Pp
567where the line containing
568.Dq Li #ethertable
569marks the start of the table.
570.Pp
571If the MAC address is not found, the script will prompt you to
572enter a hostname and IP address for the system, and this
573information will be stored in the
574.Pa /etc/hosts
575file (in memory) so you can simply store them on disk later.
576.Pp
577Note that you can use wildcards in the address part, so a line
578like the last one in the example will match any MAC address and
579avoid the request.
580.It Pa /etc/rc.conf
581This file contains a number of variables which control the
582operation of the system, such as interface configuration,
583router setup, network service startup, etc.
584For the exact list and meaning of these variables see
585.Pa /etc/rc.conf.defaults .
586.Pp
587It is worth mentioning that some of the variables let you
588overwrite the contents of some files in
589.Pa /etc .
590This option is available at the moment for
591.Pa /etc/host.conf
592and
593.Pa /etc/resolv.conf ,
594whose contents are generally very short and suitable for this
595type of updating.
596In case you use these variables, remember to use newlines
597as appropriate, e.g.\&
598.Bd -literal -offset indent
599host_conf="# this goes into /etc/host.conf
600hosts
601bind"
602.Ed
603.Pp
604Although not mandatory, in this file you should only set the
605variables indicated in
606.Pa /etc/rc.conf.defaults ,
607and avoid starting services which depend on having the network running.
608This can be done at a later time: if you set
609.Va firewall_enable Ns = Ns Qq Li YES ,
610the
611.Pa /etc/rc.firewall
612script will be run after configuring the network interfaces,
613so you can set up your firewall and safely start network services or enable
614things such as routing and bridging.
615.It Pa /etc/rc.firewall
616This script can be used to configure the
617.Xr ipfw 4
618firewall.
619On entry, the
620.Va fwcmd
621variable is set to the pathname of the firewall command,
622.Va firewall_type
623contains the value set in
624.Pa /etc/rc.conf ,
625and
626.Va hostname
627contains the name assigned to the host.
628.El
629.Pp
630There is a small script called
631.Nm update
632which can be used to edit and/or save to disk a copy of the files
633you have modified after booting.
634The script takes one or more absolute pathnames, runs the
635editor on the files passed as arguments, and then saves a
636compressed copy of the files on the disk (mounting and
637unmounting the latter around the operation).
638.Pp
639If invoked without arguments,
640.Nm update
641edits and saves
642.Pa rc.conf , rc.firewall ,
643and
644.Pa master.passwd .
645.Pp
646If one of the arguments is
647.Pa /etc
648(the directory name alone),
649then the command saves to disk (without editing)
650all the files in the directory for which a copy
651already exists on disk (e.g.\& as a result of a previous update).
652.Sh SEE ALSO
653.Xr crunchgen 1 ,
654.Xr mdconfig 8 ,
655.Xr swapon 8 ,
656.Xr vnconfig 8
657.Sh AUTHORS
658.An -nosplit
659.An Andrzej Bialecki Aq abial@FreeBSD.org ,
660with subsequent work on the scripts by
661.An Luigi Rizzo Aq luigi@iet.unipi.it
662and others.
663Man page and
664.Pa Makefiles
665created by
666.An Greg Lehey Aq grog@lemis.com .
667.Sh BUGS
668In order to build
669.Nm ,
670the kernel of the system on which it is built must have the
671.Xr vn 4
672driver installed.
673.Pp
674The build process must be run as
675.Dq root
676because of the need of running
677.Xr mdconfig 8 Ns / Ns Xr vnconfig 8
678and
679.Xr mount 8 .
680.Pp
681Building
682.Nm
683is still a black art.
684The biggest problem is determining what will fit on the
685floppies, and the only practical method is trial and error.
|