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