8 .Nd building small FreeBSD disk images
12 .Op Ar config-name Op Ar site-name
16 utility is a script which produces a minimal implementation of
20 which typically fits on a small media such as a floppy disk,
21 or can be downloaded as a
22 single image file from some media such as CDROM, flash memory, or through
27 utility was originally created to build simple standalone systems
28 such as firewalls or bridges, but because of the ability to
29 cross-build images with different source trees than the one
30 in the server, it can be extremely useful to developers to
31 test their code without having to reinstall the system.
33 The boot media (historically a floppy disk, but also small
34 CDROM or USB keys) contains a boot loader and a
35 compressed kernel which includes a memory file system.
36 Depending on the media, it might also contain a number of
37 additional files, which can be updated at run time, and are
38 used to override/update those in the memory file system.
40 The system loads the kernel in the normal way, uncompresses
41 the memory file system and mounts it as root.
42 It then updates the memory
43 file system with files from the boot media (if present),
44 and executes a specialized version of
46 The boot media (floppy, etc.) is
47 required for loading only, and typically used read-only.
48 After the boot phase, the system runs entirely from RAM.
50 The following options are available (but also check the
52 script for more details):
54 .Bl -tag -width indent
55 .It Fl -src Ar SRC_PATH
56 Use the source tree at
60 This can be useful for cross-building
63 When using this option, you must also create and initialize the subtree at
64 .Ao Ar SRC_PATH Ac Ns Pa /../usr
65 with the correct header files, libraries, and tools (such as the
67 program) that are necessary for the cross-build (see the
70 The source files are unmodified by the
73 However the source tree is not completely read-only,
76 expects the kernel configuration file to be in one of
77 its subdirectories, and also the process of initializing the
79 subtree touches some parts of the source tree (this is a bug
80 in the release build scripts which might go away with time).
82 When used together with the
84 option, this initializes the
85 .Ao Ar SRC_PATH Ac Ns Pa /../usr
86 subtree as necessary to subsequently build
90 Also build kernel modules.
91 These are not stored on the
93 image but are left available in the build directory.
95 Make the script non-interactive, skipping the initial menu
96 and proceeding with the build process without requiring user input.
98 Make the script verbose, showing
99 commands to be executed and waiting for user
100 input before executing each of them.
101 Useful for debugging.
103 Put the entire contents of the file system in the
104 memory file system image which is contained in the
106 This is the default behaviour, and is
107 extremely useful as the kernel itself can be loaded,
112 as a fully functional system.
113 .It Fl -no_all_in_mfs
114 Leaves files contained in the
118 image, so they can be loaded separately
119 from the kernel (and updated individually to
120 customize the image).
121 .It Fl -floppy_size Ar size
122 Set the size of the disk image.
123 Typical values for a floppy disk are 1440 or 2880,
124 but other values can be used for other media (flash memories,
125 CDROM, network booted kernels).
127 Clean the product of previous builds.
130 As a result of extreme size limitations, the
132 environment differs from the normal
137 There are no dynamic libraries, and there is no directory
139 As a result, only static executables may be executed.
141 In order to reduce the size of the executables, all executables on a specific
142 floppy are joined together as a single executable built with
145 Some programs are supplied in minimalistic versions, specifically
147 a cut-down version of
151 a cut-down version of
157 sources reside in the hierarchy
158 .Pa /usr/src/release/picobsd .
159 In the following discussion, all relative path names are relative to this
162 The supported build script is
163 .Pa /usr/src/release/picobsd/build/picobsd
164 which can be run from anywhere, and relies on the
166 port to build a filesystem without requiring
168 or root privileges to mount a filesystem.
169 When run in interactive mode (the default without the
171 option), the script will let you configure the various parameters
172 used to build the PicoBSD image. An image is configured
173 using the files and directories described below.
174 The base system contains a template, called
176 for historical reasons,
177 that can be used as a base for building various kinds
178 of network appliances.
180 You can define your own PicoBSD configuration, by creating a directory
181 with a name of your choice (e.g.\&
184 some of the following files and directories.
186 information on how to construct these files, look at one
189 configurations as a reference.
190 .Bl -tag -width indent
192 The kernel configuration file (required).
193 This is a mostly standard
194 kernel configuration file, possibly stripped down by removing
195 unnecessary drivers and options to reduce the kernel's size.
197 To be recognised as a
199 kernel config file, the file must also contain the line
202 below, and a matching
205 .Bd -literal -offset indent
206 #marker def_sz init MFS_inodes floppy_inodes
207 #PicoBSD 4200 init 8192 32768
208 options MD_ROOT_SIZE=4200 # same as def_sz
211 This informs the script of the size of the memory file system and
212 provides a few other details on how to build the image.
215 configuration (required).
216 It contains the list of directories containing program sources,
217 the list of binaries to be built, and the list of libraries that
221 manpage for the exact details on the syntax of this file.
223 The following issues are particularly important when dealing
229 We can pass build options to those makefiles which understand
230 that, in order to reduce the size of the programs.
231 This is achieved with a line of the form
233 .Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..."
235 When providing the list of directories where source files are, it
236 is convenient to list the following entry first:
238 .Dl "srcdirs /usr/src/release/picobsd/tinyware"
242 versions of the programs will be found there.
246 is replaced with the full pathname of the directory where the
248 configuration resides (i.e., the one where we find
249 .Pa PICOBSD , crunch.conf ,
251 This can be useful to refer source code that resides within a
252 configuration, e.g.\&
254 .Dl "srcdirs @__CWD__@/src"
257 Shell variables, sourced by the
260 The most important variables here are:
261 .Bl -tag -width ".Va MY_DEVS"
267 Should be set to the list of devices to be created in the
269 directory of the image (it is really the argument passed to
271 so refer to that manpage for the names).
273 Size (in kilobytes) of the
279 which produces an image suitable for a standard floppy.
281 If you plan to store the image on a CDROM (e.g.\& using
284 floppy emulation), you can set
287 If you are planning to dump the image onto a hard disk
288 (either in a partition or on the whole disk), you
289 are not restricted to one of the standard floppy sizes.
290 Using a large image size per se does not waste RAM at runtime,
291 because only the files that are actually loaded from the image
292 contribute to the memory usage.
294 Contains a list of files to be imported in the floppy tree.
295 Absolute names refer to the standard file system, relative
296 names refer to the root of the source tree being used
299 You can normally use this option if you want to import
300 files such as shared libraries, or databases, without
301 having to replicate them first in your configuration
306 .It Pa floppy.tree.exclude
307 List of files from the standard floppy tree which
308 we do not want to be copied (optional).
310 Local additions to the standard floppy tree (optional).
311 The content of this subtree will be copied as-is into the
313 .It Pa floppy.tree. Ns Aq Ar site-name
314 Same as above, but site-specific (optional).
317 More information on the build process can be found in the
321 .Sh USING ALTERNATE SOURCE TREES
322 The build script can be instructed to use an alternate source tree
326 The tree that you specify must contain full sources for the kernel
327 and for all programs that you want to include in your image.
328 As an example, to cross-build the
331 using RELENG_4 sources, you can do the following:
332 .Bd -literal -offset indent
333 cd <some_empty_directory>
335 (cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
336 picobsd --src FOO/src --init # this is needed only once
337 picobsd --src FOO/src -n -v bridge
340 If the build is successful, the directory
341 .Pa build_dir-bridge/
344 that can be downloaded with
346 a floppy image called
348 plus the products of the compilation in other directories.
349 If you want to modify the source tree in
351 a new image can be produced by simply running
353 .Dl "picobsd --src FOO/src -n -v bridge"
355 whereas if the change affects include files or libraries
356 you first need to update them, e.g.\& by re-running
358 .Dl "picobsd --src FOO/src --init # this is needed only once"
360 as you would normally do for any change of this kind.
361 .Sh INSTALLING PicoBSD
365 is run from a floppy disk, where it can be installed with a simple
367 .Dl "dd if=picobsd.bin of=/dev/rfd0"
369 and the floppy is ready to boot.
370 .Ss Hard Disk Install
371 The same process can be used to store the image on a hard disk
372 (entire volume or one of the slices):
373 .Bd -literal -offset indent
374 dd if=picobsd.bin of=/dev/ad2
375 dd if=picobsd.bin of=/dev/ad2s3
376 dd if=picobsd.bin of=/dev/ad2 oseek=NN
379 The first form will install the image on the entire disk, and it
380 should work in the same way as for a floppy.
382 The second form will install the image
383 on slice number 3 (which should be large enough to store the
384 contents of the image).
385 However, the process will only have success if the
386 partition does not contain a valid disklabel, otherwise the kernel will
387 likely prevent overwriting the label.
388 In this case you can use the
389 third form, replacing
391 with the actual start of the partition
392 (which you can determine using
394 Note that after saving the image to the slice, it will not yet be
398 command to properly initialize the label (do not ask why!).
399 One way to do this is
400 .Bd -literal -offset indent
401 disklabel -w ad0s2 auto
405 and from the editor enter a line corresponding to the actual partition, e.g.\&
406 if the image has 2.88MB (5760 sectors) you need to enter the following
407 line for the partition:
409 .Dl "a: 5760 0 4.2BSD 512 4096"
411 At this point the partition is bootable.
412 Note that the image size can be smaller than the slice size
413 (indicated as partition
416 Another option is to put the image on a CDROM.
422 then you can produce a bootable
424 image (and burn it) with the
426 .Bd -literal -offset indent
427 mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
428 -o cd.img build_dir-foo
429 burncd -f /dev/acd0c -s 4 data cd.img fixate
432 Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
433 most likely will not work.
434 .Ss Booting From The Network
435 Yet another way to use
437 is to boot the image off the network.
438 For this purpose you should use the uncompressed kernel which is
439 available as a byproduct of the compilation.
440 Refer to the documentation
441 for network booting for more details, the
443 kernel is bootable as a standard
449 insert the floppy and reset the machine.
450 The boot procedure is similar to the
454 Booting from a floppy is normally rather slow (in the order of 1-2
455 minutes), things are much faster if you store your image on
456 a hard disk, Compact Flash, or CDROM.
460 to load the preloaded, uncompressed kernel image
461 which is a byproduct of the
465 the load time is a matter of a few seconds, even on a 10Mbit/s
470 loads the root file system from the memory file system, starts
472 and passes control to a first startup script,
474 The latter populates the
478 directories with the default files, then tries to identify the boot
479 device (floppy, hard disk partition) and possibly override the contents
480 of the root file system with files read from the boot device.
481 This allows you to store local configuration on the same media.
482 After this phase the boot device is no longer used, unless the
483 user specifically does it.
485 After this, control is transferred to a second script,
487 (which can be overridden from the boot device).
488 This script tries to associate a hostname to the system by using
489 the MAC address of the first ethernet interface as a key, and
492 Then control is passed to the main user configuration script,
494 which is supposed to override the value of a number of configuration
495 variables which have been pre-set in
496 .Pa /etc/rc.conf.defaults .
499 variable to create different configurations from the same file.
500 After taking control back,
502 completes the initializations, and as part of this
503 it configures network interfaces and optionally calls the
504 firewall configuration script,
505 .Pa /etc/rc.firewall ,
506 where the user can store his own firewall configuration.
510 runs entirely from main memory, and has no swap space, unless you
511 explicitly request it.
512 The boot device is also not used anymore after
514 takes control, again, unless you explicitly request it.
515 .Sh CONFIGURING a PicoBSD system
518 system can be configured through a few files which are read at boot
519 time, very much like a standard
522 There are, however, some minor differences to reduce the
523 number of files to store and/or customize, thus saving space.
524 Among the files to configure we have the following:
525 .Bl -tag -width indent
527 Traditionally, this file contains the IP-to-hostname mappings.
528 In addition to this, the
530 version of this file also contains
531 a mapping between Ethernet (MAC) addresses and hostnames, as follows:
532 .Bd -literal -offset indent
533 #ethertable start of the ethernet->hostname mapping
534 # mac_address hostname
535 # 00:12:34:56:78:9a pinco
540 where the line containing
542 marks the start of the table.
544 If the MAC address is not found, the script will prompt you to
545 enter a hostname and IP address for the system, and this
546 information will be stored in the
548 file (in memory) so you can simply store them on disk later.
550 Note that you can use wildcards in the address part, so a line
551 like the last one in the example will match any MAC address and
554 This file contains a number of variables which control the
555 operation of the system, such as interface configuration,
556 router setup, network service startup, etc.
557 For the exact list and meaning of these variables see
558 .Pa /etc/rc.conf.defaults .
560 It is worth mentioning that some of the variables let you
561 overwrite the contents of some files in
563 This option is available at the moment for
566 .Pa /etc/resolv.conf ,
567 whose contents are generally very short and suitable for this
569 In case you use these variables, remember to use newlines
570 as appropriate, e.g.\&
571 .Bd -literal -offset indent
572 host_conf="# this goes into /etc/host.conf
577 Although not mandatory, in this file you should only set the
578 variables indicated in
579 .Pa /etc/rc.conf.defaults ,
580 and avoid starting services which depend on having the network running.
581 This can be done at a later time: if you set
582 .Va firewall_enable Ns = Ns Qq Li YES ,
585 script will be run after configuring the network interfaces,
586 so you can set up your firewall and safely start network services or enable
587 things such as routing and bridging.
588 .It Pa /etc/rc.firewall
589 This script can be used to configure the
594 variable is set to the pathname of the firewall command,
596 contains the value set in
600 contains the name assigned to the host.
603 There is a small script called
605 which can be used to edit and/or save to disk a copy of the files
606 you have modified after booting.
607 The script takes one or more absolute pathnames, runs the
608 editor on the files passed as arguments, and then saves a
609 compressed copy of the files on the disk (mounting and
610 unmounting the latter around the operation).
612 If invoked without arguments,
615 .Pa rc.conf , rc.firewall ,
619 If one of the arguments is
621 (the directory name alone),
622 then the command saves to disk (without editing)
623 all the files in the directory for which a copy
624 already exists on disk (e.g.\& as a result of a previous update).
632 .An Andrzej Bialecki Aq abial@FreeBSD.org ,
633 with subsequent work on the scripts by
634 .An Luigi Rizzo Aq luigi@iet.unipi.it
639 .An Greg Lehey Aq grog@lemis.com .
643 is still a black art.
644 The biggest problem is determining what will fit on the
645 floppies, and the only practical method is trial and error.