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