2 .\" $FreeBSD: src/share/man/man8/picobsd.8,v 1.1.2.14 2002/12/29 16:35:39 schweikh Exp $
3 .\" $DragonFly: src/share/man/man8/Attic/picobsd.8,v 1.2 2003/06/17 04:37:00 dillon Exp $
9 .Nd floppy disk based FreeBSD system
13 .Op Ar floppy-type Op Ar site-name
16 is a script which can be used to produce a minimal implementation of
20 which typically fits on one floppy disk, or can be downloaded as a
21 single image file from some media such as CDROM, flash memory, or through
25 was originally created to build simple standalone systems
26 such as firewalls or bridges, but because of the ability to
27 cross-build images with different source trees than the one
28 in the server, it can be extremely useful to developers to
29 test their code without having to reinstall the system.
31 The boot media (typically a floppy disk) contains a boot loader and a
32 compressed kernel which includes a memory file system.
33 Depending on the media, it might also contain a number of
34 additional files, which can be updated at run time, and are
35 used to override/update those in the memory file system.
37 The system loads the kernel in the normal way, uncompresses
38 the memory file system and mounts it as root.
39 It then updates the memory
40 filesystem with files from the boot media (if present),
41 and executes a specialized version of
43 The boot media (floppy, etc.) is
44 required for loading only, and typically used read-only.
45 After the boot phase, the system runs entirely from RAM.
47 The following options are available (but also check the
49 script for more details):
51 .Bl -tag -width indent
52 .It Fl -src Ar SRC_PATH
53 Use the source tree at
57 This can be useful for cross-building floppy images.
58 When using this option, you must also create and initialize the subtree at
59 .Ao Ar SRC_PATH Ac Ns Pa /../usr
60 with the correct header files, libraries, and tools (such as the
62 program) that are necessary for the cross-build (see the
65 The source files are unmodified by the
68 However the source tree is not completely read-only,
71 expects the kernel configuration file to be in one of
72 its subdirectories, and also the process of initializing the
74 subtree touches some parts of the source tree (this is a bug
75 in the release build scripts which might go away with time).
77 When used together with the
79 option, this initializes the
80 .Ao Ar SRC_PATH Ac Ns Pa /../usr
81 subtree as necessary to subsequently build
85 Also build kernel modules.
86 These are not stored on the floppy
87 image but are left available in the build directory.
89 Make the script non-interactive.
90 Do not show the initial menu, and
91 proceed to the build process without requiring user input.
93 Make the script verbose, showing
94 commands to be executed and waiting for user
95 input before executing each of them.
98 Put the entire contents of the filesystem in the
99 memory filesystem image which is contained in the
101 This is the default behaviour, and is
102 extremely useful as the kernel itself can be loaded,
107 as a fully functional system.
108 .It Fl -no_all_in_mfs
109 Leaves files contained in the
111 on the floppy image, so they can be loaded separately
112 from the kernel (and updated individually to
113 customize the floppy image).
114 .It Fl -floppy_size Ar size
115 Set the size of the floppy image.
117 than 1440 can be used for images that are burned
120 Clean the product of previous builds.
123 As a result of extreme size limitations, the
125 environment differs from the normal
130 There are no dynamic libraries, and there is no directory
132 As a result, only static executables may be executed.
134 In order to reduce the size of the executables, all executables on a specific
135 floppy are joined together as a single executable built with
138 Some programs are supplied in minimalistic versions, specifically
140 a cut-down version of
144 a cut-down version of
150 sources reside in the hierarchy
151 .Pa /usr/src/release/picobsd .
152 In the following discussion, all relative path names are relative to this
156 build process has changed slightly over time, in order to cope
157 with the unavoidable increase of code size, which requires more and more
158 tricks to cram as much as possible onto the floppies.
161 the supported build script is
162 .Pa /usr/src/release/picobsd/build/picobsd
163 which can be run from anywhere.
164 When run in interactive mode (the default without the
166 option), the script will let you configure the various parameters
167 used to build the floppy image.
168 The following kinds of floppy are envisaged, and we try to keep them
169 functional and fitting in the 1.44MB floppy despite the unavoidable
170 increases in the size of the kernel and its applications:
171 .Bl -hang -width ".Pa bridge"
173 configuration suitable for bridges, routers and firewalls.
176 The following configurations are also present but for reference
178 Many of them are irremediably out of date and no effort
179 is done to keep them in good shape:
180 .Bl -hang -width ".Pa bridge"
182 configuration suitable for dial-out
186 configuration suitable for dial-in
190 configuration suitable for general networking.
192 configuration suitable for use as a router.
193 This particular configuration
194 aims to work on minimal hardware.
197 These configurations serve only as examples for
198 your own modification.
199 Not all of them have been tested,
200 and you might need small tweaks to the configuration
201 files to make them work or even fit into the
202 available disk space as code size increases.
204 You can define your own floppy type, by creating a directory
205 with a name of your choice (e.g.\&
208 some of the following files and directories.
210 information on how to construct these files, look at one
213 configurations as a reference.
214 .Bl -tag -width indent
216 The kernel configuration file (required).
217 This is a mostly standard
218 kernel configuration file, possibly stripped down by removing
219 unnecessary drivers and options to reduce the kernel's size.
221 To be recognised as a
223 kernel config file, the file must also contain the line
226 below, and a matching
229 .Bd -literal -offset indent
230 #marker def_sz init MFS_inodes floppy_inodes
231 #PicoBSD 4200 init 8192 32768
232 options MD_ROOT_SIZE=4200 # same as def_sz
235 This informs the script of the size of the memory filesystem and
236 provides a few other details on how to build the image.
239 configuration (required).
240 It contains the list of directories containing program sources,
241 the list of binaries to be built, and the list of libraries that
245 manpage for the exact details on the syntax of this file.
247 The following issues are particularly important when dealing
253 we can pass build options to those Makefile's which understand
254 that, in order to reduce the size of the programs.
255 This is achieved with a line of the form
256 .Bd -literal -offset indent
257 buildopts -DNOPAM -DRELEASE_CRUNCH ...
260 When providing the list of directories where source files are, it
261 is convenient to list the following entry first:
263 srcdirs /usr/src/release/picobsd/tinyware
267 -specific versions of the programs will be found there.
271 is replaced with the full pathname of the directory where the
273 configuration resides (i.e. the one where we find
274 .Pa PICOBSD , crunch.conf ,
276 This can be useful to refer source code that resides within a
278 .Bd -literal -offset indent
279 srcdirs @__CWD__@/src
283 Shell variables, sourced by the
286 The most important variables here are:
287 .Bl -tag -width MY_DEVS
289 (not used in -CURRENT where we have DEVFS).
290 Should be set to the list of devices to be created in the
292 directory of the image (it is really the argument passed to
294 so refer to that manpage for the names).
296 Size (in kilobytes) of the
302 which produces an image suitable for a standard floppy.
304 If you plan to store the image on a CDROM (e.g. using
307 floppy emulation), you can set
310 If you are planning to dump the image onto a hard disk
311 (either in a partition or on the whole disk), you
312 are not restricted to one of the standard floppy sizes.
313 Using a large image size per se does not waste RAM at runtime,
314 because only the files that are actually loaded from the image
315 contribute to the memory usage.
317 Contains a list of files to be imported in the floppy_tree.
318 Absolute names refer to the standard filesystem, relative
319 names refer to the root of the source tree being used
323 You can normally use this option if you want to import
324 files such as shared libraries, or databases, without
325 having to replicate them first in your configuration
331 .It Pa floppy.tree.exclude
332 List of files from the standard floppy tree which
333 we do not want to be copied (optional).
335 Local additions to the standard floppy tree (optional).
336 The content of this subtree will be copied as-is into the
338 .It Pa floppy.tree. Ns Aq Ar site-name
339 Same as above, but site-specific (optional).
342 More information on the build process can be found in the
346 Sample 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
349 The build script can be instructed to use an alternate source tree
353 The tree that you specify must contain full sources for the kernel
354 and for all programs that you want to include in your image.
355 As an example, to cross-build the
358 using RELENG_4 sources, you can do the following:
359 .Bd -literal -offset indent
360 cd <some_empty_directory>
362 (cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
363 picobsd --src FOO/src --init # this is needed only once
364 picobsd --src FOO/src -n -v bridge
367 If the build is successful, the directory
368 .Pa build_dir-bridge/
371 that can be downloaded with
373 a floppy image called
375 plus the products of the compilation in other directories.
376 If you want to modify the source tree in
378 a new image can be produced by simply running
380 .Dl "picobsd --src FOO/src -n -v bridge"
382 whereas if the change affects include files or libraries
383 you first need to update them, e.g. by running first
385 .Dl "picobsd --src FOO/src --init # this is needed only once"
387 as you would normally do for any change of this kind.
388 .Sh INSTALLING PicoBSD
392 is run from a floppy disk, where it can be installed with a simple
394 .Dl "dd if=picobsd.bin of=/dev/rfd0"
396 and the floppy is ready to boot.
397 .Ss Hard Disk Install
398 The 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
401 dd if=picobsd.bin of=/dev/ad2
402 dd if=picobsd.bin of=/dev/ad2s3
403 dd if=picobsd.bin of=/dev/ad2 oseek=NN
406 The first form will install the image on the entire disk, and it
407 should work in the same way as for a floppy.
409 The second form will install the image
410 on slice number 3 (which should be large enough to store the
411 contents of the image).
412 However, the process will only have success if the
413 partition does not contain a valid disklabel, otherwise the kernel will
414 likely prevent overwriting the label.
415 In this case you can use the
416 third form, replacing
418 with the actual start of the partition
419 (which you can determine using
421 Note that after saving the image to the slice, it will not yet be
425 command to properly initialize the label (do not ask why!).
426 One way to do this is
427 .Bd -literal -offset indent
428 disklabel -w ad0s2 auto
432 and from the editor enter a line corresponding to the actual partition, e.g.\&
433 if the image has 2.88MB (5760 sectors) you need to enter the following
434 line for the partition:
436 .Dl "a: 5760 0 4.2BSD 512 4096"
438 At this point the partition is bootable.
439 Note that the image size can be smaller than the slice size
440 (indicated as partition
443 Another option is to put the image on a CDROM.
449 then you can produce a bootable
451 image (and burn it) with the
453 .Bd -literal -offset indent
454 mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
455 -o cd.img build_dir-foo
456 burncd -f /dev/acd0c -s 4 data cd.img fixate
459 Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
460 most likely will not work.
461 .Ss Booting From The Network
462 Yet another way to use
464 is to boot the image off the network.
465 For this purpose you should use the uncompressed kernel which is
466 available as a byproduct of the compilation.
467 Refer to the documentation
468 for network booting for more details, the
470 kernel is bootable as a standard
476 insert the floppy and reset the machine.
477 The boot procedure is similar to the
481 Booting from a floppy is normally rather slow (in the order of 1-2
482 minutes), things are much faster if you store your image on
483 a hard disk, Compact Flash, or CDROM.
487 to load the preloaded, uncompressed kernel image
488 which is a byproduct of the
492 the load time is a matter of a few seconds, even on a 10Mbit/s
497 loads the root filesystem from the memory file system, starts
499 and passes control to a first startup script,
501 The latter populates the
505 directories with the default files, then tries to identify the boot
506 device (floppy, hard disk partition) and possibly override the contents
507 of the root filesystem with files read from the boot device.
508 This allows you to store local configuration on the same media.
509 After this phase the boot device is no longer used, unless the
510 user specifically does it.
512 After this, control is transferred to a second script,
514 (which can be overridden from the boot device).
515 This script tries to associate a hostname to the system by using
516 the MAC address of the first ethernet interface as a key, and
519 Then control is passed to the main user configuration script,
521 which is supposed to override the value of a number of configuration
522 variables which have been pre-set in
523 .Pa /etc/rc.conf.defaults .
526 variable to create different configurations from the same file.
527 After taking control back,
529 completes the initializations, and as part of this
530 it configures network interfaces and optionally calls the
531 firewall configuration script,
532 .Pa /etc/rc.firewall ,
533 where the user can store his own firewall configuration.
537 runs entirely from main memory, and has no swap space, unless you
538 explicitly request it.
539 The boot device is also not used anymore after
541 takes control, again, unless you explicitly request it.
542 .Sh CONFIGURING a PicoBSD system
545 system can be configured through a few files which are read at boot
546 time, very much like a standard
549 There are, however, some minor differences to reduce the
550 number of files to store and/or customize, thus saving space.
551 Among the files to configure we have the following:
552 .Bl -tag -width indent
554 Traditionally, this file contains the IP-to-hostname mappings.
555 In addition to this, the
557 version of this file also contains
558 a 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
567 where the line containing
569 marks the start of the table.
571 If the MAC address is not found, the script will prompt you to
572 enter a hostname and IP address for the system, and this
573 information will be stored in the
575 file (in memory) so you can simply store them on disk later.
577 Note that you can use wildcards in the address part, so a line
578 like the last one in the example will match any MAC address and
581 This file contains a number of variables which control the
582 operation of the system, such as interface configuration,
583 router setup, network service startup, etc.
584 For the exact list and meaning of these variables see
585 .Pa /etc/rc.conf.defaults .
587 It is worth mentioning that some of the variables let you
588 overwrite the contents of some files in
590 This option is available at the moment for
593 .Pa /etc/resolv.conf ,
594 whose contents are generally very short and suitable for this
596 In case you use these variables, remember to use newlines
597 as appropriate, e.g.\&
598 .Bd -literal -offset indent
599 host_conf="# this goes into /etc/host.conf
604 Although not mandatory, in this file you should only set the
605 variables indicated in
606 .Pa /etc/rc.conf.defaults ,
607 and avoid starting services which depend on having the network running.
608 This can be done at a later time: if you set
609 .Va firewall_enable Ns = Ns Qq Li YES ,
612 script will be run after configuring the network interfaces,
613 so you can set up your firewall and safely start network services or enable
614 things such as routing and bridging.
615 .It Pa /etc/rc.firewall
616 This script can be used to configure the
621 variable is set to the pathname of the firewall command,
623 contains the value set in
627 contains the name assigned to the host.
630 There is a small script called
632 which can be used to edit and/or save to disk a copy of the files
633 you have modified after booting.
634 The script takes one or more absolute pathnames, runs the
635 editor on the files passed as arguments, and then saves a
636 compressed copy of the files on the disk (mounting and
637 unmounting the latter around the operation).
639 If invoked without arguments,
642 .Pa rc.conf , rc.firewall ,
646 If one of the arguments is
648 (the directory name alone),
649 then the command saves to disk (without editing)
650 all the files in the directory for which a copy
651 already exists on disk (e.g. as a result of a previous update).
659 .An Andrzej Bialecki Aq abial@FreeBSD.org ,
660 with subsequent work on the scripts by
661 .An Luigi Rizzo Aq luigi@iet.unipi.it
666 .An Greg Lehey Aq grog@lemis.com .
670 the kernel of the system on which it is built must have the
674 The build process must be run as
676 because of the need of running
684 is still a black art.
685 The biggest problem is determining what will fit on the
686 floppies, and the only practical method is trial and error.