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
|
<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
"../../../share/xml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
%entities;
]>
<article lang='en'>
<articleinfo>
<title>Introduction to NanoBSD</title>
<authorgroup>
<author>
<firstname>Daniel</firstname>
<surname>Gerzo</surname>
<!-- 14 March 2006 -->
</author>
</authorgroup>
<copyright>
<year>2006</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>This document provides information about
the <application>NanoBSD</application> tools, which can be used to
create &os; system images for embedded applications, suitable for
use on a Compact Flash card (or other mass storage medium).</para>
</abstract>
</articleinfo>
<sect1 id="intro">
<title>Introduction to NanoBSD</title>
<indexterm><primary>NanoBSD</primary></indexterm>
<para><application>NanoBSD</application> is a tool currently
developed by &a.phk;. It creates a &os; system image for embedded
applications, suitable for use on a Compact Flash card (or other
mass storage medium).</para>
<para>It can be used to build specialized install images, designed for
easy installation and maintenance of systems commonly
called <quote>computer appliances</quote>. Computer appliances have
their hardware and software bundled in the product, which means all
applications are pre-installed. The appliance is plugged into an
existing network and can begin working (almost) immediately.</para>
<para>The features of <application>NanoBSD</application> include:</para>
<itemizedlist>
<listitem>
<para>Ports and packages work as in &os; — Every single
application can be installed and used in
a <application>NanoBSD</application> image, the same way as in
&os;.</para>
</listitem>
<listitem>
<para>No missing functionality — If it is possible to do
something with &os;, it is possible to do the same thing with
<application>NanoBSD</application>, unless the specific feature
or features were explicitly removed from
the <application>NanoBSD</application> image when it was
created.</para>
</listitem>
<listitem>
<para>Everything is read-only at run-time — It is safe to
pull the power-plug. There is no necessity to run
&man.fsck.8; after a non-graceful shutdown of the system.</para>
</listitem>
<listitem>
<para>Easy to build and customize — Making use of just one
shell script and one configuration file it is possible to
build reduced and customized images satisfying any arbitrary set of
requirements.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="howto">
<title>NanoBSD Howto</title>
<sect2 id="design">
<title>The design of NanoBSD</title>
<para>Once the image is present on the medium, it is possible to
boot <application>NanoBSD</application>. The mass storage
medium is divided into three parts by default:</para>
<itemizedlist>
<listitem>
<para>Two image partitions: <literal>code#1</literal>
and <literal>code#2</literal>.</para>
</listitem>
<listitem>
<para>The configuration file partition, which can be mounted
under the <filename class="directory">/cfg</filename> directory
at run time.</para>
</listitem>
</itemizedlist>
<para>These partitions are normally mounted read-only.</para>
<para>The <filename class="directory">/etc</filename> and
<filename class="directory">/var</filename> directories are
&man.md.4; (malloc) disks.</para>
<para>The configuration file partition persists under the
<filename class="directory">/cfg</filename> directory. It
contains files for <filename class="directory">/etc</filename>
directory and is briefly mounted read-only right after the
system boot, therefore it is required to copy modified files
from <filename class="directory">/etc</filename> back to the
<filename class="directory">/cfg</filename> directory if changes
are expected to persist after the system restarts.</para>
<example>
<title>Making persistent changes to <filename>/etc/resolv.conf</filename></title>
<screen>&prompt.root; <userinput>vi /etc/resolv.conf</userinput>
[...]
&prompt.root; <userinput>mount /cfg</userinput>
&prompt.root; <userinput>cp /etc/resolv.conf /cfg</userinput>
&prompt.root; <userinput>umount /cfg</userinput></screen>
</example>
<note>
<para>The partition containing
<filename class="directory">/cfg</filename> should be mounted
only at boot time and while overriding the configuration
files.</para>
<para>Keeping <filename class="directory">/cfg</filename> mounted at
all times is not a good idea, especially if
the <application>NanoBSD</application> system runs off a mass
storage medium that may be adversely affected by a large number
of writes to the partition (i.e. when the filesystem syncer
flushes data to the system disks).</para>
</note>
</sect2>
<sect2>
<title>Building a NanoBSD image</title>
<para>A <application>NanoBSD</application> image is built using a
simple <filename>nanobsd.sh</filename> shell script, which can
be found in the
<filename class="directory"><replaceable>/usr</replaceable>/src/tools/tools/nanobsd</filename>
directory. This script creates an image, which can be copied on
the storage medium using the &man.dd.1; utility.</para>
<para>The necessary commands to build a
<application>NanoBSD</application> image are:</para>
<screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co id="nbsd-cd"/>
&prompt.root; <userinput>sh nanobsd.sh</userinput> <co id="nbsd-sh"/>
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co id="nbsd-cd2"/>
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co id="nbsd-dd"/></screen>
<calloutlist>
<callout arearefs="nbsd-cd">
<para>Change the current directory to the base directory of the
<application>NanoBSD</application> build script.</para>
</callout>
<callout arearefs="nbsd-sh">
<para>Start the build process.</para>
</callout>
<callout arearefs="nbsd-cd2">
<para>Change the current directory to the place where the built
images are located.</para>
</callout>
<callout arearefs="nbsd-dd">
<para>Install <application>NanoBSD</application> onto the
storage medium.</para>
</callout>
</calloutlist>
</sect2>
<sect2>
<title>Customizing a NanoBSD image</title>
<para>This is probably the most important and most interesting
feature of <application>NanoBSD</application>. This is also
where you will be spending most of the time when
developing with <application>NanoBSD</application>.</para>
<para>Invocation of the following command will force the
<filename>nanobsd.sh</filename> to read its configuration from
the <filename>myconf.nano</filename> file located in the current
directory:</para>
<screen>&prompt.root; <userinput>sh nanobsd.sh -c myconf.nano</userinput></screen>
<para>Customization is done in two ways:</para>
<itemizedlist>
<listitem>
<para>Configuration options</para>
</listitem>
<listitem>
<para>Custom functions</para>
</listitem>
</itemizedlist>
<sect3>
<title>Configuration options</title>
<para>With configuration settings, it is possible to configure options
passed to both the <maketarget>buildworld</maketarget>
and <maketarget>installworld</maketarget> stages of the
<application>NanoBSD</application> build process, as well as internal
options passed to the main build process of
<application>NanoBSD</application>. Through these options it is
possible to cut the system down, so it will fit on as little as
64MB. You can use the configuration options to trim down &os; even
more, until it will consists of just the kernel and two or three
files in the userland.</para>
<para>The configuration file consists of configuration options,
which override the default values. The most important
directives are:</para>
<itemizedlist>
<listitem>
<para><literal>NANO_NAME</literal> — Name of build
(used to construct the workdir names).</para>
</listitem>
<listitem>
<para><literal>NANO_SRC</literal> — Path to the source
tree used to build the image.</para>
</listitem>
<listitem>
<para><literal>NANO_KERNEL</literal> — Name of kernel
configuration file used to build kernel.</para>
</listitem>
<listitem>
<para><literal>CONF_BUILD</literal> — Options passed
to the <maketarget>buildworld</maketarget> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_INSTALL</literal> — Options passed
to the <maketarget>installworld</maketarget> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_WORLD</literal> — Options passed to both
the <maketarget>buildworld</maketarget> and
the <maketarget>installworld</maketarget> stage of the build.</para>
</listitem>
<listitem>
<para><literal>FlashDevice</literal> — Defines what type of
media to use. Check the <filename>FlashDevice.sub</filename>
file for more details.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Custom functions</title>
<para>It is possible to fine-tune
<application>NanoBSD</application> using shell functions in
the configuration file. The following example illustrates the
basic model of custom functions:</para>
<programlisting>cust_foo () (
echo "bar=baz" > \
${NANO_WORLDDIR}/etc/foo
)
customize_cmd cust_foo</programlisting>
<para>A more useful example of a customization function is the
following, which changes the default size of the
<filename class="directory">/etc</filename> directory
from 5MB to 30MB:</para>
<programlisting>cust_etc_size () (
cd ${NANO_WORLDDIR}/conf
echo 30000 > default/etc/md_size
)
customize_cmd cust_etc_size</programlisting>
<para>There are a few default pre-defined customization functions
ready for use:</para>
<itemizedlist>
<listitem>
<para><literal>cust_comconsole</literal> — Disables
&man.getty.8; on the VGA devices
(the <filename>/dev/ttyv*</filename> device nodes) and enables
the use of the COM1 serial port as the system console.</para>
</listitem>
<listitem>
<para><literal>cust_allow_ssh_root</literal> — Allow
<username>root</username> to login via &man.sshd.8;.</para>
</listitem>
<listitem>
<para><literal>cust_install_files</literal> —
Installs files from the
<filename class="directory">nanobsd/Files</filename>
directory, which contains some useful scripts for system
administration.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Adding packages</title>
<para>Packages can be added to a <application>NanoBSD</application>
image using a custom function. The following function will install
all the packages located in
<filename>/usr/src/tools/tools/nanobsd/packages</filename>:</para>
<programlisting>install_packages () (
mkdir -p ${NANO_WORLDDIR}/packages
cp /usr/src/tools/tools/nanobsd/packages/* ${NANO_WORLDDIR}/packages
chroot ${NANO_WORLDDIR} sh -c 'cd packages; pkg_add -v *;cd ..;'
rm -rf ${NANO_WORLDDIR}/packages
)
customize_cmd install_packages</programlisting>
</sect3>
<sect3>
<title>Configuration file example</title>
<para>A complete example of a configuration file for building a
custom <application>NanoBSD</application> image can be:</para>
<programlisting>NANO_NAME=custom
NANO_SRC=/usr/src
NANO_KERNEL=MYKERNEL
NANO_IMAGES=2
CONF_BUILD='
NO_KLDLOAD=YES
NO_NETGRAPH=YES
NO_PAM=YES
'
CONF_INSTALL='
NO_ACPI=YES
NO_BLUETOOTH=YES
NO_CVS=YES
NO_FORTRAN=YES
NO_HTML=YES
NO_LPR=YES
NO_MAN=YES
NO_SENDMAIL=YES
NO_SHAREDOCS=YES
NO_EXAMPLES=YES
NO_INSTALLLIB=YES
NO_CALENDAR=YES
NO_MISC=YES
NO_SHARE=YES
'
CONF_WORLD='
NO_BIND=YES
NO_MODULES=YES
NO_KERBEROS=YES
NO_GAMES=YES
NO_RESCUE=YES
NO_LOCALES=YES
NO_SYSCONS=YES
NO_INFO=YES
'
FlashDevice SanDisk 1G
cust_nobeastie() (
touch ${NANO_WORLDDIR}/boot/loader.conf
echo "beastie_disable=\"YES\"" >> ${NANO_WORLDDIR}/boot/loader.conf
)
customize_cmd cust_comconsole
customize_cmd cust_install_files
customize_cmd cust_allow_ssh_root
customize_cmd cust_nobeastie</programlisting>
</sect3>
</sect2>
<sect2>
<title>Updating NanoBSD</title>
<para>The update process of <application>NanoBSD</application> is
relatively simple:</para>
<procedure>
<step>
<para>Build a new <application>NanoBSD</application> image, as
usual.</para>
</step>
<step>
<para>Upload the new image into an unused partition of a
running <application>NanoBSD</application> appliance.</para>
<para>The most important difference of this step from the
initial <application>NanoBSD</application> installation is that
now instead of using the <filename>_.disk.full</filename> file
(which contains an image of the entire disk),
the <filename>_.disk.image</filename> image is installed (which
contains an image of a single system partition).</para>
</step>
<step>
<para>Reboot, and start the system from the newly installed
partition.</para>
</step>
<step>
<para>If all goes well, the upgrade is finished.</para>
</step>
<step>
<para>If anything goes wrong, reboot back into the previous
partition (which contains the old, working image), to restore system
functionality as fast as possible. Fix any problems of the new
build, and repeat the process.</para>
</step>
</procedure>
<para>To install new image onto the running
<application>NanoBSD</application> system, it is possible to use
either the <filename>updatep1</filename> or
<filename>updatep2</filename> script located in the
<filename class="directory">/root</filename> directory, depending
from which partition is running the current system.</para>
<para>According to which services are available on host serving
new <application>NanoBSD</application> image and what type of
transfer is preferred, it is possible to examine one of these
three ways:</para>
<sect3>
<title>Using &man.ftp.1;</title>
<para>If the transfer speed is in first place, use this
example:</para>
<screen>&prompt.root; <userinput>ftp myhost
get _.disk.image "| sh updatep1"</userinput></screen>
</sect3>
<sect3>
<title>Using &man.ssh.1;</title>
<para>If a secure transfer is preferred, consider using this
example:</para>
<screen>&prompt.root; <userinput>ssh myhost cat _.disk.image.gz | zcat | sh updatep1</userinput></screen>
</sect3>
<sect3>
<title>Using &man.nc.1;</title>
<para>Try this example if the remote host is not running neither
&man.ftpd.8; or &man.sshd.8; service:</para>
<procedure>
<step>
<para>At first, open a TCP listener on host serving the
image and make it send the image to client:</para>
<screen>myhost&prompt.root; <userinput>nc -l <replaceable>2222</replaceable> < _.disk.image</userinput></screen>
<note>
<para>Make sure that the used port is not blocked to
receive incoming connections from
<application>NanoBSD</application> host by
firewall.</para>
</note>
</step>
<step>
<para>Connect to the host serving new image and execute
<filename>updatep1</filename> script:</para>
<screen>&prompt.root; <userinput>nc myhost <replaceable>2222</replaceable> | sh updatep1</userinput></screen>
</step>
</procedure>
</sect3>
</sect2>
</sect1>
</article>
|