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.
173 An image is configured
174 using the files and directories described below.
175 The base system contains a template, called
177 for historical reasons,
178 that can be used as a base for building various kinds
179 of network appliances.
181 You can define your own PicoBSD configuration, by creating a directory
182 with a name of your choice (e.g.\&
185 some of the following files and directories.
187 information on how to construct these files, look at one
190 configurations as a reference.
191 .Bl -tag -width indent
193 The kernel configuration file (required).
194 This is a mostly standard
195 kernel configuration file, possibly stripped down by removing
196 unnecessary drivers and options to reduce the kernel's size.
198 To be recognised as a
200 kernel config file, the file must also contain the line
203 below, and a matching
206 .Bd -literal -offset indent
207 #marker def_sz init MFS_inodes floppy_inodes
208 #PicoBSD 4200 init 8192 32768
209 options MD_ROOT_SIZE=4200 # same as def_sz
212 This informs the script of the size of the memory file system and
213 provides a few other details on how to build the image.
216 configuration (required).
217 It contains the list of directories containing program sources,
218 the list of binaries to be built, and the list of libraries that
222 manpage for the exact details on the syntax of this file.
224 The following issues are particularly important when dealing
230 We can pass build options to those makefiles which understand
231 that, in order to reduce the size of the programs.
232 This is achieved with a line of the form
234 .Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..."
236 When providing the list of directories where source files are, it
237 is convenient to list the following entry first:
239 .Dl "srcdirs /usr/src/release/picobsd/tinyware"
243 versions of the programs will be found there.
247 is replaced with the full pathname of the directory where the
249 configuration resides (i.e., the one where we find
250 .Pa PICOBSD , crunch.conf ,
252 This can be useful to refer source code that resides within a
253 configuration, e.g.\&
255 .Dl "srcdirs @__CWD__@/src"
258 Shell variables, sourced by the
261 The most important variables here are:
262 .Bl -tag -width ".Va MY_DEVS"
268 Should be set to the list of devices to be created in the
270 directory of the image (it is really the argument passed to
272 so refer to that manpage for the names).
274 Size (in kilobytes) of the
280 which produces an image suitable for a standard floppy.
282 If you plan to store the image on a CDROM (e.g.\& using
285 floppy emulation), you can set
288 If you are planning to dump the image onto a hard disk
289 (either in a partition or on the whole disk), you
290 are not restricted to one of the standard floppy sizes.
291 Using a large image size per se does not waste RAM at runtime,
292 because only the files that are actually loaded from the image
293 contribute to the memory usage.
295 Contains a list of files to be imported in the floppy tree.
296 Absolute names refer to the standard file system, relative
297 names refer to the root of the source tree being used
300 You can normally use this option if you want to import
301 files such as shared libraries, or databases, without
302 having to replicate them first in your configuration
307 .It Pa floppy.tree.exclude
308 List of files from the standard floppy tree which
309 we do not want to be copied (optional).
311 Local additions to the standard floppy tree (optional).
312 The content of this subtree will be copied as-is into the
314 .It Pa floppy.tree. Ns Aq Ar site-name
315 Same as above, but site-specific (optional).
318 More information on the build process can be found in the
322 .Sh USING ALTERNATE SOURCE TREES
323 The build script can be instructed to use an alternate source tree
327 The tree that you specify must contain full sources for the kernel
328 and for all programs that you want to include in your image.
329 As an example, to cross-build the
332 using RELENG_4 sources, you can do the following:
333 .Bd -literal -offset indent
334 cd <some_empty_directory>
336 (cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
337 picobsd --src FOO/src --init # this is needed only once
338 picobsd --src FOO/src -n -v bridge
341 If the build is successful, the directory
342 .Pa build_dir-bridge/
345 that can be downloaded with
347 a floppy image called
349 plus the products of the compilation in other directories.
350 If you want to modify the source tree in
352 a new image can be produced by simply running
354 .Dl "picobsd --src FOO/src -n -v bridge"
356 whereas if the change affects include files or libraries
357 you first need to update them, e.g.\& by re-running
359 .Dl "picobsd --src FOO/src --init # this is needed only once"
361 as you would normally do for any change of this kind.
362 .Sh INSTALLING PicoBSD
366 is run from a floppy disk, where it can be installed with a simple
368 .Dl "dd if=picobsd.bin of=/dev/rfd0"
370 and the floppy is ready to boot.
371 .Ss Hard Disk Install
372 The same process can be used to store the image on a hard disk
373 (entire volume or one of the slices):
374 .Bd -literal -offset indent
375 dd if=picobsd.bin of=/dev/ad2
376 dd if=picobsd.bin of=/dev/ad2s3
377 dd if=picobsd.bin of=/dev/ad2 oseek=NN
380 The first form will install the image on the entire disk, and it
381 should work in the same way as for a floppy.
383 The second form will install the image
384 on slice number 3 (which should be large enough to store the
385 contents of the image).
386 However, the process will only have success if the
387 partition does not contain a valid disklabel, otherwise the kernel will
388 likely prevent overwriting the label.
389 In this case you can use the
390 third form, replacing
392 with the actual start of the partition
393 (which you can determine using
395 Note that after saving the image to the slice, it will not yet be
399 command to properly initialize the label (do not ask why!).
400 One way to do this is
401 .Bd -literal -offset indent
402 disklabel -w ad0s2 auto
406 and from the editor enter a line corresponding to the actual partition, e.g.\&
407 if the image has 2.88MB (5760 sectors) you need to enter the following
408 line for the partition:
410 .Dl "a: 5760 0 4.2BSD 512 4096"
412 At this point the partition is bootable.
413 Note that the image size can be smaller than the slice size
414 (indicated as partition
417 Another option is to put the image on a CDROM.
423 then you can produce a bootable
425 image (and burn it) with the
427 .Bd -literal -offset indent
428 mkisofs -b picobsd.bin -c boot.catalog -d -N -D -R -T \\
429 -o cd.img build_dir-foo
430 burncd -f /dev/acd0c -s 4 data cd.img fixate
433 Note that the image size is restricted to 1.44MB or 2.88MB, other sizes
434 most likely will not work.
435 .Ss Booting From The Network
436 Yet another way to use
438 is to boot the image off the network.
439 For this purpose you should use the uncompressed kernel which is
440 available as a byproduct of the compilation.
441 Refer to the documentation
442 for network booting for more details, the
444 kernel is bootable as a standard
450 insert the floppy and reset the machine.
451 The boot procedure is similar to the
455 Booting from a floppy is normally rather slow (in the order of 1-2
456 minutes), things are much faster if you store your image on
457 a hard disk, Compact Flash, or CDROM.
461 to load the preloaded, uncompressed kernel image
462 which is a byproduct of the
466 the load time is a matter of a few seconds, even on a 10Mbit/s
471 loads the root file system from the memory file system, starts
473 and passes control to a first startup script,
475 The latter populates the
479 directories with the default files, then tries to identify the boot
480 device (floppy, hard disk partition) and possibly override the contents
481 of the root file system with files read from the boot device.
482 This allows you to store local configuration on the same media.
483 After this phase the boot device is no longer used, unless the
484 user specifically does it.
486 After this, control is transferred to a second script,
488 (which can be overridden from the boot device).
489 This script tries to associate a hostname to the system by using
490 the MAC address of the first ethernet interface as a key, and
493 Then control is passed to the main user configuration script,
495 which is supposed to override the value of a number of configuration
496 variables which have been pre-set in
497 .Pa /etc/rc.conf.defaults .
500 variable to create different configurations from the same file.
501 After taking control back,
503 completes the initializations, and as part of this
504 it configures network interfaces and optionally calls the
505 firewall configuration script,
506 .Pa /etc/rc.firewall ,
507 where the user can store his own firewall configuration.
511 runs entirely from main memory, and has no swap space, unless you
512 explicitly request it.
513 The boot device is also not used anymore after
515 takes control, again, unless you explicitly request it.
516 .Sh CONFIGURING a PicoBSD system
519 system can be configured through a few files which are read at boot
520 time, very much like a standard
523 There are, however, some minor differences to reduce the
524 number of files to store and/or customize, thus saving space.
525 Among the files to configure we have the following:
526 .Bl -tag -width indent
528 Traditionally, this file contains the IP-to-hostname mappings.
529 In addition to this, the
531 version of this file also contains
532 a mapping between Ethernet (MAC) addresses and hostnames, as follows:
533 .Bd -literal -offset indent
534 #ethertable start of the ethernet->hostname mapping
535 # mac_address hostname
536 # 00:12:34:56:78:9a pinco
541 where the line containing
543 marks the start of the table.
545 If the MAC address is not found, the script will prompt you to
546 enter a hostname and IP address for the system, and this
547 information will be stored in the
549 file (in memory) so you can simply store them on disk later.
551 Note that you can use wildcards in the address part, so a line
552 like the last one in the example will match any MAC address and
555 This file contains a number of variables which control the
556 operation of the system, such as interface configuration,
557 router setup, network service startup, etc.
558 For the exact list and meaning of these variables see
559 .Pa /etc/rc.conf.defaults .
561 It is worth mentioning that some of the variables let you
562 overwrite the contents of some files in
564 This option is available at the moment for
567 .Pa /etc/resolv.conf ,
568 whose contents are generally very short and suitable for this
570 In case you use these variables, remember to use newlines
571 as appropriate, e.g.\&
572 .Bd -literal -offset indent
573 host_conf="# this goes into /etc/host.conf
578 Although not mandatory, in this file you should only set the
579 variables indicated in
580 .Pa /etc/rc.conf.defaults ,
581 and avoid starting services which depend on having the network running.
582 This can be done at a later time: if you set
583 .Va firewall_enable Ns = Ns Qq Li YES ,
586 script will be run after configuring the network interfaces,
587 so you can set up your firewall and safely start network services or enable
588 things such as routing and bridging.
589 .It Pa /etc/rc.firewall
590 This script can be used to configure the
595 variable is set to the pathname of the firewall command,
597 contains the value set in
601 contains the name assigned to the host.
604 There is a small script called
606 which can be used to edit and/or save to disk a copy of the files
607 you have modified after booting.
608 The script takes one or more absolute pathnames, runs the
609 editor on the files passed as arguments, and then saves a
610 compressed copy of the files on the disk (mounting and
611 unmounting the latter around the operation).
613 If invoked without arguments,
616 .Pa rc.conf , rc.firewall ,
620 If one of the arguments is
622 (the directory name alone),
623 then the command saves to disk (without editing)
624 all the files in the directory for which a copy
625 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.