Merge from vendor branch LIBSTDC++:
[dragonfly.git] / share / man / man8 / picobsd.8
1 .\" -*- nroff-fill -*-
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 $
4 .Dd March 9, 2002
5 .Os
6 .Dt PICOBSD 8
7 .Sh NAME
8 .Nm picobsd
9 .Nd floppy disk based FreeBSD system
10 .Sh SYNOPSIS
11 .Nm
12 .Op Ar options
13 .Op Ar floppy-type Op Ar site-name
14 .Sh DESCRIPTION
15 .Nm
16 is a script which can be used to produce a minimal implementation of
17 .Fx
18 (historically called
19 .Nm PicoBSD )
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
22 .Xr etherboot .
23 .Pp
24 .Nm
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.
30 .Pp
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.
36 .Pp
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
42 .Pa /etc/rc .
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.
46 .Pp
47 The following options are available (but also check the
48 .Nm
49 script for more details):
50 .Pp
51 .Bl -tag -width indent
52 .It Fl -src Ar SRC_PATH
53 Use the source tree at
54 .Ar SRC_PATH
55 instead the one at
56 .Pa /usr/src .
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
61 .Xr config 8
62 program) that are necessary for the cross-build (see the
63 .Fl -init
64 option below).
65 The source files are unmodified by the
66 .Nm
67 script.
68 However the source tree is not completely read-only,
69 because
70 .Xr config 8
71 expects the kernel configuration file to be in one of
72 its subdirectories, and also the process of initializing the
73 .Pa usr
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).
76 .It Fl -init
77 When used together with the
78 .Fl -src
79 option, this initializes the
80 .Ao Ar SRC_PATH Ac Ns Pa /../usr
81 subtree as necessary to subsequently build
82 .Nm
83 images.
84 .It Fl -modules
85 Also build kernel modules.
86 These are not stored on the floppy
87 image but are left available in the build directory.
88 .It Fl n
89 Make the script non-interactive.
90 Do not show the initial menu, and
91 proceed to the build process without requiring user input.
92 .It Fl v
93 Make the script verbose, showing
94 commands to be executed and waiting for user
95 input before executing each of them.
96 Useful for debugging.
97 .It Fl -all_in_mfs
98 Put the entire contents of the filesystem in the
99 memory filesystem image which is contained in the
100 kernel.
101 This is the default behaviour, and is
102 extremely useful as the kernel itself can be loaded,
103 using
104 .Xr etherboot
105 or
106 .Xr pxeboot 8 ,
107 as a fully functional system.
108 .It Fl -no_all_in_mfs
109 Leaves files contained in the
110 .Pa floppy.tree
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.
116 Values other
117 than 1440 can be used for images that are burned
118 into a CDROM.
119 .It Fl c , clean
120 Clean the product of previous builds.
121 .El
122 .Sh ENVIRONMENT
123 As a result of extreme size limitations, the
124 .Nm
125 environment differs from the normal
126 .Fx
127 in a number of ways:
128 .Bl -bullet
129 .It
130 There are no dynamic libraries, and there is no directory
131 .Pa /usr/lib .
132 As a result, only static executables may be executed.
133 .It
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
136 .Xr crunchgen 1 .
137 .It
138 Some programs are supplied in minimalistic versions, specifically
139 .Nm ns ,
140 a cut-down version of
141 .Xr netstat 1 ,
142 and
143 .Nm vm ,
144 a cut-down version of
145 .Xr vmstat 8 .
146 .El
147 .Sh BUILDING PicoBSD
148 The
149 .Nm
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
153 directory.
154 The
155 .Nm
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.
159 Starting from
160 .Fx 4.3 ,
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
165 .Fl -n
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"
172 .It Pa bridge
173 configuration suitable for bridges, routers and firewalls.
174 .El
175 .Pp
176 The following configurations are also present but for reference
177 only.
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"
181 .It Pa dial
182 configuration suitable for dial-out
183 .Pq Xr ppp 8
184 networking.
185 .It Pa isp
186 configuration suitable for dial-in
187 .Pq Xr ppp 8
188 networking.
189 .It Pa net
190 configuration suitable for general networking.
191 .It Pa router
192 configuration suitable for use as a router.
193 This particular configuration
194 aims to work on minimal hardware.
195 .El
196 .Pp
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.
203 .Pp
204 You can define your own floppy type, by creating a directory
205 with a name of your choice (e.g.\&
206 .Pa FOO )
207 which contains
208 some of the following files and directories.
209 For more
210 information on how to construct these files, look at one
211 of the standard
212 .Nm
213 configurations as a reference.
214 .Bl -tag -width indent
215 .It Pa PICOBSD
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.
220 .Pp
221 To be recognised as a
222 .Nm
223 kernel config file, the file must also contain the line
224 beginning with
225 .Dq Li #PicoBSD
226 below, and a matching
227 .Dv MD_ROOT_SIZE
228 option:
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
233 .Ed
234 .Pp
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.
237 .It Pa crunch.conf
238 .Xr crunchgen 1
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
242 these programs use.
243 See the
244 .Xr crunchgen 1
245 manpage for the exact details on the syntax of this file.
246 .Pp
247 The following issues are particularly important when dealing
248 with
249 .Nm
250 configurations:
251 .Bl -bullet
252 .It
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 ...
258 .Ed
259 .It
260 When providing the list of directories where source files are, it
261 is convenient to list the following entry first:
262 .Bd -literal
263 srcdirs /usr/src/release/picobsd/tinyware
264 .Ed
265 so that
266 .Nm
267 -specific versions of the programs will be found there.
268 .It
269 The string
270 .Pa @__CWD__@
271 is replaced with the full pathname of the directory where the
272 .Nm
273 configuration resides (i.e. the one where we find
274 .Pa PICOBSD , crunch.conf ,
275 and so on).
276 This can be useful to refer source code that resides within a
277 configuration, e.g.
278 .Bd -literal -offset indent
279 srcdirs @__CWD__@/src
280 .Ed
281 .El
282 .It Pa config
283 Shell variables, sourced by the
284 .Nm
285 script (optional).
286 The most important variables here are:
287 .Bl -tag -width MY_DEVS
288 .It Va 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
291 .Pa /dev
292 directory of the image (it is really the argument passed to
293 .Xr MAKEDEV 8 ,
294 so refer to that manpage for the names).
295 .It Va fd_size
296 Size (in kilobytes) of the
297 .Nm
298 image.
299 By default,
300 .Va fd_size
301 is set to 1440
302 which produces an image suitable for a standard floppy.
303 .Pp
304 If you plan to store the image on a CDROM (e.g. using
305 the
306 .Dq "El Torito"
307 floppy emulation), you can set
308 .Va fd_size
309 equal to 2880.
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.
316 .It Va import_files
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
320 (i.e.
321 .Va SRC_PATH/..
322 ).
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
326 under the
327 .Pa floppy.tree/
328 directory.
329 .El
330 .Pp
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).
334 .It Pa floppy.tree/
335 Local additions to the standard floppy tree (optional).
336 The content of this subtree will be copied as-is into the
337 floppy image.
338 .It Pa floppy.tree. Ns Aq Ar site-name
339 Same as above, but site-specific (optional).
340 .El
341 .Pp
342 More information on the build process can be found in the
343 comments in the
344 .Nm
345 script.
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
350 using the
351 .Fl -src Ar SRC_PATH
352 option.
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
356 .Pa bridge
357 floppy
358 using RELENG_4 sources, you can do the following:
359 .Bd -literal -offset indent
360 cd <some_empty_directory>
361 mkdir FOO
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
365 .Ed
366 .Pp
367 If the build is successful, the directory
368 .Pa build_dir-bridge/
369 will contain a
370 .Pa kernel
371 that can be downloaded with
372 .Xr etherboot ,
373 a floppy image called
374 .Pa picobsd.bin ,
375 plus the products of the compilation in other directories.
376 If you want to modify the source tree in
377 .Pa FOO/src ,
378 a new image can be produced by simply running
379 .Pp
380 .Dl "picobsd --src FOO/src -n -v bridge"
381 .Pp
382 whereas if the change affects include files or libraries
383 you first need to update them, e.g. by running first
384 .Pp
385 .Dl "picobsd --src FOO/src --init  # this is needed only once"
386 .Pp
387 as you would normally do for any change of this kind.
388 .Sh INSTALLING PicoBSD
389 .Ss Floppy Install
390 Historically,
391 .Nm
392 is run from a floppy disk, where it can be installed with a simple
393 .Pp
394 .Dl "dd if=picobsd.bin of=/dev/rfd0"
395 .Pp
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
404 .Ed
405 .Pp
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.
408 .Pp
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
417 .Ar NN
418 with the actual start of the partition
419 (which you can determine using
420 .Xr fdisk 8 ) .
421 Note that after saving the image to the slice, it will not yet be
422 recognised.
423 You have to use the
424 .Xr disklabel 8
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
429 disklabel -e ad0s2
430 .Ed
431 .Pp
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:
435 .Pp
436 .Dl "a: 5760   0    4.2BSD   512   4096"
437 .Pp
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
441 .Dq Li c: ) .
442 .Ss CDROM Install
443 Another option is to put the image on a CDROM.
444 Assuming your image
445 for disk type
446 .Pa foo
447 is in the directory
448 .Pa build_dir-foo
449 then you can produce a bootable
450 .Dq "El Torito"
451 image (and burn it) with the
452 following command:
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
457 .Ed
458 .Pp
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
463 .Nm
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
469 .Nm
470 kernel is bootable as a standard
471 .Fx
472 kernel.
473 .Sh BOOTING PicoBSD
474 To boot
475 .Nm ,
476 insert the floppy and reset the machine.
477 The boot procedure is similar to the
478 standard
479 .Fx
480 boot.
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.
484 .Pp
485 You can also use
486 .Xr etherboot
487 to load the preloaded, uncompressed kernel image
488 which is a byproduct of the
489 .Nm
490 build.
491 In this case
492 the load time is a matter of a few seconds, even on a 10Mbit/s
493 ethernet.
494 .Pp
495 After booting,
496 .Nm
497 loads the root filesystem from the memory file system, starts
498 .Pa /sbin/init ,
499 and passes control to a first startup script,
500 .Pa /etc/rc .
501 The latter populates the
502 .Pa /etc
503 and
504 .Pa /root
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.
511 .Pp
512 After this, control is transferred to a second script,
513 .Pa /etc/rc1
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
517 .Pa /etc/hosts
518 as a lookup table.
519 Then control is passed to the main user configuration script,
520 .Pa /etc/rc.conf ,
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 .
524 You can use the
525 .Va hostname
526 variable to create different configurations from the same file.
527 After taking control back,
528 .Pa /etc/rc1
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.
534 .Pp
535 Note that by default
536 .Nm
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
540 .Pa /etc/rc1
541 takes control, again, unless you explicitly request it.
542 .Sh CONFIGURING a PicoBSD system
543 The operation of a
544 .Nm
545 system can be configured through a few files which are read at boot
546 time, very much like a standard
547 .Fx
548 system.
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
553 .It Pa /etc/hosts
554 Traditionally, this file contains the IP-to-hostname mappings.
555 In addition to this, the
556 .Nm
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
563 # 12:34:56:*            pallino
564 # *                     this-matches-all
565 .Ed
566 .Pp
567 where the line containing
568 .Dq Li #ethertable
569 marks the start of the table.
570 .Pp
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
574 .Pa /etc/hosts
575 file (in memory) so you can simply store them on disk later.
576 .Pp
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
579 avoid the request.
580 .It Pa /etc/rc.conf
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 .
586 .Pp
587 It is worth mentioning that some of the variables let you
588 overwrite the contents of some files in
589 .Pa /etc .
590 This option is available at the moment for
591 .Pa /etc/host.conf
592 and
593 .Pa /etc/resolv.conf ,
594 whose contents are generally very short and suitable for this
595 type of updating.
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
600 hosts
601 bind"
602 .Ed
603 .Pp
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 ,
610 the
611 .Pa /etc/rc.firewall
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
617 .Xr ipfw 4
618 firewall.
619 On entry, the
620 .Va fwcmd
621 variable is set to the pathname of the firewall command,
622 .Va firewall_type
623 contains the value set in
624 .Pa /etc/rc.conf ,
625 and
626 .Va hostname
627 contains the name assigned to the host.
628 .El
629 .Pp
630 There is a small script called
631 .Nm update
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).
638 .Pp
639 If invoked without arguments,
640 .Nm update
641 edits and saves
642 .Pa rc.conf , rc.firewall ,
643 and
644 .Pa master.passwd .
645 .Pp
646 If one of the arguments is
647 .Pa /etc
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).
652 .Sh SEE ALSO
653 .Xr crunchgen 1 ,
654 .Xr mdconfig 8 ,
655 .Xr swapon 8 ,
656 .Xr vnconfig 8
657 .Sh AUTHORS
658 .An -nosplit
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
662 and others.
663 Man page and
664 .Pa Makefiles
665 created by
666 .An Greg Lehey Aq grog@lemis.com .
667 .Sh BUGS
668 In order to build
669 .Nm ,
670 the kernel of the system on which it is built must have the
671 .Xr vn 4
672 driver installed.
673 .Pp
674 The build process must be run as
675 .Dq root
676 because of the need of running
677 .Xr mdconfig 8 /
678 .Xr vnconfig 8
679 and
680 .Xr mount 8 .
681 .Pp
682 Building
683 .Nm
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.