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).
53 The most important options for common operations are
58 .Bl -tag -width indent
61 Put the entire contents of the file system in the
62 memory file system image which is contained in the
64 This is the default behaviour, and is
65 extremely useful as the kernel itself can be loaded,
72 Clean the product of previous builds.
75 Specify a file that contains additional config commands.
77 .It Fl -floppy_size Ar size
78 Set the size of the disk image.
79 Typical values for a floppy disk are 1440 or 2880,
80 but other values can be used for other media (flash memories,
81 CDROM, network booted kernels).
82 Note that this option is overridden by the content of the
83 config files (config in the image tree, or the one
88 When used together with the
90 option, this initializes the
91 .Ao Ar SRC_PATH Ac Ns Pa /../usr
92 subtree as necessary to subsequently build
97 Generate an ISO image,
99 in addition to the disk image
103 Also build kernel modules.
104 These are not stored on the
106 image but are left available in the build directory.
109 Make the script non-interactive, skipping the initial menu
110 and proceeding with the build process without requiring user input.
112 .It Fl -no_all_in_mfs
113 Leaves files contained in the
117 image, so they can be loaded separately
118 from the kernel (and updated individually to
119 customize the image).
122 Omit /boot/loader, just rely on boot2 to load the kernel.
123 This saves some space but may have problems with kernels > 4MB.
125 .It Fl -objdir Ar directory
126 Specify a directory with the result of a previous buildworld.
127 This saves the need for an
129 call before creating an image.
131 .It Fl -src Ar SRC_PATH
132 Use the source tree at
136 This can be useful for cross-building
139 When using this option, you must also create and initialize the subtree at
140 .Ao Ar SRC_PATH Ac Ns Pa /../usr
141 with the correct header files, libraries, and tools (such as the
143 program) that are necessary for the cross-build (see the
146 The source files are unmodified by the
149 However the source tree is not completely read-only,
152 expects the kernel configuration file to be in one of
153 its subdirectories, and also the process of initializing the
155 subtree touches some parts of the source tree (this is a bug
156 in the release build scripts which might go away with time).
159 Make the script verbose, showing
160 commands to be executed and waiting for user
161 input before executing each of them.
162 Useful for debugging.
163 as a fully functional system.
166 As a result of extreme size limitations, the
168 environment differs from the normal
173 There are no dynamic libraries, and there is no directory
175 As a result, only static executables may be executed.
177 In order to reduce the size of the executables, all executables on a specific
178 floppy are joined together as a single executable built with
181 Some programs are supplied in minimalistic versions, specifically
183 a cut-down version of
187 a cut-down version of
193 sources reside in the hierarchy
194 .Pa /usr/src/release/picobsd .
195 In the following discussion, all relative path names are relative to this
198 The supported build script is
199 .Pa /usr/src/release/picobsd/build/picobsd
200 which can be run from anywhere, and relies on the
202 port to build a filesystem without requiring
204 or root privileges to mount a filesystem.
205 When run in interactive mode (the default without the
207 option), the script will let you configure the various parameters
208 used to build the PicoBSD image.
209 An image is configured
210 using the files and directories described below.
211 The base system contains a template, called
213 for historical reasons,
214 that can be used as a base for building various kinds
215 of network appliances.
217 You can define your own PicoBSD configuration, by creating a directory
218 with a name of your choice (e.g.\&
221 some of the following files and directories.
223 information on how to construct these files, look at one
226 configurations as a reference.
227 .Bl -tag -width indent
229 The kernel configuration file (required).
230 This is a mostly standard
231 kernel configuration file, possibly stripped down by removing
232 unnecessary drivers and options to reduce the kernel's size.
234 To be recognised as a
236 kernel config file, the file must also contain the line
239 below, and a matching
242 .Bd -literal -offset indent
243 #marker def_sz init MFS_inodes floppy_inodes
244 #PicoBSD 4200 init 8192 32768
245 options MD_ROOT_SIZE=4200 # same as def_sz
248 This informs the script of the size of the memory file system and
249 provides a few other details on how to build the image.
252 configuration (required).
253 It contains the list of directories containing program sources,
254 the list of binaries to be built, and the list of libraries that
258 manpage for the exact details on the syntax of this file.
260 The following issues are particularly important when dealing
266 We can pass build options to those makefiles which understand
267 that, in order to reduce the size of the programs.
268 This is achieved with a line of the form
270 .Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..."
272 When providing the list of directories where source files are, it
273 is convenient to list the following entry first:
275 .Dl "srcdirs /usr/src/release/picobsd/tinyware"
279 versions of the programs will be found there.
283 is replaced with the full pathname of the directory where the
285 configuration resides (i.e., the one where we find
286 .Pa PICOBSD , crunch.conf ,
288 This can be useful to refer source code that resides within a
289 configuration, e.g.\&
291 .Dl "srcdirs @__CWD__@/src"
294 Shell variables, sourced by the
297 The most important variables here are:
298 .Bl -tag -width ".Va MY_DEVS"
304 Should be set to the list of devices to be created in the
306 directory of the image (it is really the argument passed to
308 so refer to that manpage for the names).
310 Size (in kilobytes) of the
316 which produces an image suitable for a standard floppy.
318 If you plan to store the image on a CDROM (e.g.\& using
321 floppy emulation), you can set
324 If you are planning to dump the image onto a hard disk
325 (either in a partition or on the whole disk), you
326 are not restricted to one of the standard floppy sizes.
327 Using a large image size per se does not waste RAM at runtime,
328 because only the files that are actually loaded from the image
329 contribute to the memory usage.
331 Contains a list of files to be imported in the floppy tree.
332 Absolute names refer to the standard file system, relative
333 names refer to the root of the source tree being used
336 You can normally use this option if you want to import
337 files such as shared libraries, or databases, without
338 having to replicate them first in your configuration
343 .It Pa floppy.tree.exclude
344 List of files from the standard floppy tree which
345 we do not want to be copied (optional).
347 Local additions to the standard floppy tree (optional).
348 The content of this subtree will be copied as-is into the
350 .It Pa floppy.tree. Ns Aq Ar site-name
351 Same as above, but site-specific (optional).
354 More information on the build process can be found in the
358 .Sh USING ALTERNATE SOURCE TREES
359 The build script can be instructed to use an alternate source tree
363 The tree that you specify must contain full sources for the kernel
364 and for all programs that you want to include in your image.
365 As an example, to cross-build the
368 using RELENG_4 sources, you can do the following:
369 .Bd -literal -offset indent
370 cd <some_empty_directory>
372 (cd FOO; cvs -d<my_repository> co -rRELENG_4 src)
373 picobsd --src FOO/src --init # this is needed only once
374 picobsd --src FOO/src -n -v bridge
377 If the build is successful, the directory
378 .Pa build_dir-bridge/
381 that can be downloaded with etherboot, a floppy image called
383 plus the products of the compilation in other directories.
384 If you want to modify the source tree in
386 a new image can be produced by simply running
388 .Dl "picobsd --src FOO/src -n -v bridge"
390 whereas if the change affects include files or libraries
391 you first need to update them, e.g.\& by re-running
393 .Dl "picobsd --src FOO/src --init # this is needed only once"
395 as you would normally do for any change of this kind.
396 .Sh INSTALLING PicoBSD
400 is run from a floppy disk, where it can be installed with a simple
402 .Dl "dd if=picobsd.bin of=/dev/rfd0"
404 and the floppy is ready to boot.
405 .Ss Hard Disk Install
406 The same process can be used to store the image on a hard disk
407 (entire volume or one of the slices):
408 .Bd -literal -offset indent
409 dd if=picobsd.bin of=/dev/ada2
410 dd if=picobsd.bin of=/dev/ada2s3
411 dd if=picobsd.bin of=/dev/ada2 oseek=NN
414 The first form will install the image on the entire disk, and it
415 should work in the same way as for a floppy.
417 The second form will install the image
418 on slice number 3 (which should be large enough to store the
419 contents of the image).
420 However, the process will only have success if the
421 partition does not contain a valid disklabel, otherwise the kernel will
422 likely prevent overwriting the label.
423 In this case you can use the
424 third form, replacing
426 with the actual start of the partition
427 (which you can determine using
429 Note that after saving the image to the slice, it will not yet be
433 command to properly initialize the label (do not ask why!).
434 One way to do this is
435 .Bd -literal -offset indent
436 disklabel -w ada0s2 auto
440 and from the editor enter a line corresponding to the actual partition, e.g.\&
441 if the image has 2.88MB (5760 sectors) you need to enter the following
442 line for the partition:
444 .Dl "a: 5760 0 4.2BSD 512 4096"
446 At this point the partition is bootable.
447 Note that the image size can be smaller than the slice size
448 (indicated as partition
452 can produce an ISO image named picobsd.iso,
455 emulation, so it has no size restrictions.
456 Installing means just burning a media with the file.
457 .Ss Booting From The Network
458 Yet another way to use
460 is to boot the image off the network.
461 For this purpose you should use the uncompressed kernel which is
462 available as a byproduct of the compilation.
463 Refer to the documentation
464 for network booting for more details, the
466 kernel is bootable as a standard
472 insert the floppy and reset the machine.
473 The boot procedure is similar to the
477 Booting from a floppy is normally rather slow (in the order of 1-2
478 minutes), things are much faster if you store your image on
479 a hard disk, Compact Flash, or CDROM.
481 You can also use etherboot to load the preloaded, uncompressed kernel image
482 which is a byproduct of the
486 the load time is a matter of a few seconds, even on a 10Mbit/s
491 loads the root file system from the memory file system, starts
493 and passes control to a first startup script,
495 The latter populates the
499 directories with the default files, then tries to identify the boot
500 device (floppy, hard disk partition) and possibly override the contents
501 of the root file system with files read from the boot device.
502 This allows you to store local configuration on the same media.
503 After this phase the boot device is no longer used, unless the
504 user specifically does it.
506 After this, control is transferred to a second script,
508 (which can be overridden from the boot device).
509 This script tries to associate a hostname to the system by using
510 the MAC address of the first ethernet interface as a key, and
513 Then control is passed to the main user configuration script,
515 which is supposed to override the value of a number of configuration
516 variables which have been pre-set in
517 .Pa /etc/rc.conf.defaults .
520 variable to create different configurations from the same file.
521 After taking control back,
523 completes the initializations, and as part of this
524 it configures network interfaces and optionally calls the
525 firewall configuration script,
526 .Pa /etc/rc.firewall ,
527 where the user can store his own firewall configuration.
531 runs entirely from main memory, and has no swap space, unless you
532 explicitly request it.
533 The boot device is also not used anymore after
535 takes control, again, unless you explicitly request it.
536 .Sh CONFIGURING a PicoBSD system
539 system can be configured through a few files which are read at boot
540 time, very much like a standard
543 There are, however, some minor differences to reduce the
544 number of files to store and/or customize, thus saving space.
545 Among the files to configure we have the following:
546 .Bl -tag -width indent
548 Traditionally, this file contains the IP-to-hostname mappings.
549 In addition to this, the
551 version of this file also contains
552 a mapping between Ethernet (MAC) addresses and hostnames, as follows:
553 .Bd -literal -offset indent
554 #ethertable start of the ethernet->hostname mapping
555 # mac_address hostname
556 # 00:12:34:56:78:9a pinco
561 where the line containing
563 marks the start of the table.
565 If the MAC address is not found, the script will prompt you to
566 enter a hostname and IP address for the system, and this
567 information will be stored in the
569 file (in memory) so you can simply store them on disk later.
571 Note that you can use wildcards in the address part, so a line
572 like the last one in the example will match any MAC address and
575 This file contains a number of variables which control the
576 operation of the system, such as interface configuration,
577 router setup, network service startup, etc.
578 For the exact list and meaning of these variables see
579 .Pa /etc/rc.conf.defaults .
581 It is worth mentioning that some of the variables let you
582 overwrite the contents of some files in
584 This option is available at the moment for
587 .Pa /etc/resolv.conf ,
588 whose contents are generally very short and suitable for this
590 In case you use these variables, remember to use newlines
591 as appropriate, e.g.\&
592 .Bd -literal -offset indent
593 host_conf="# this goes into /etc/host.conf
598 Although not mandatory, in this file you should only set the
599 variables indicated in
600 .Pa /etc/rc.conf.defaults ,
601 and avoid starting services which depend on having the network running.
602 This can be done at a later time: if you set
603 .Va firewall_enable Ns = Ns Qq Li YES ,
606 script will be run after configuring the network interfaces,
607 so you can set up your firewall and safely start network services or enable
608 things such as routing and bridging.
609 .It Pa /etc/rc.firewall
610 This script can be used to configure the
615 variable is set to the pathname of the firewall command,
617 contains the value set in
621 contains the name assigned to the host.
624 There is a small script called
626 which can be used to edit and/or save to disk a copy of the files
627 you have modified after booting.
628 The script takes one or more absolute pathnames, runs the
629 editor on the files passed as arguments, and then saves a
630 compressed copy of the files on the disk (mounting and
631 unmounting the latter around the operation).
633 If invoked without arguments,
636 .Pa rc.conf , rc.firewall ,
640 If one of the arguments is
642 (the directory name alone),
643 then the command saves to disk (without editing)
644 all the files in the directory for which a copy
645 already exists on disk (e.g.\& as a result of a previous update).
653 .An Andrzej Bialecki Aq abial@FreeBSD.org ,
654 with subsequent work on the scripts by
655 .An Luigi Rizzo Aq luigi@iet.unipi.it
660 .An Greg Lehey Aq grog@lemis.com .
662 Documentation is still incomplete.