summaryrefslogtreecommitdiffstats
path: root/share/man/man8/nanobsd.8
blob: 0309c4e424c8f46719629ac1032ffb69199c1bbf (plain)
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
.\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd May 20, 2010
.Dt NANOBSD 8
.Os
.Sh NAME
.Nm nanobsd.sh
.Nd utility used to create a FreeBSD system image suitable for embedded
applications
.Sh SYNOPSIS
.Nm
.Op Fl bhknw
.Op Fl c Ar config-file
.Sh DESCRIPTION
The
.Nm
utility is a script which produces a minimal implementation of
.Fx
(called
.Nm NanoBSD ) ,
which typically fits on a small media such as a Compact Flash card,
or other mass storage medium.
It can be used to build specialized install images, designed for easy
installation and maintenance.
.Pp
The following options are available:
.Bl -tag -width ".Fl c Ar config-file" -offset indent
.It Fl b
Skip the build stages (both for kernel and world).
.It Fl c Ar config-file
Specify the configuration file to use.
.It Fl h
Display usage information.
.It Fl k
Skip the
.Cm buildkernel
stage of the build.
.It Fl n
Do not cleanup before each build stage.
This suppresses the normal cleanup work done before the
.Cm buildworld
stage and adds -DNO_CLEAN to the make command line
used for each build stage (world and kernel).
.It Fl w
Skip the
.Cm buildworld
stage of the build.
.El
.Pp
The features of
.Nm NanoBSD
include:
.Pp
.Bl -bullet -offset indent -compact
.It
Ports and packages work as in
.Fx .
Every single application can be installed and used in a
.Nm NanoBSD
image, the same way as in
.Fx .
.It
No missing functionality.
If it is possible to do something with
.Fx ,
it is possible to do the same thing with
.Nm NanoBSD ,
unless the specific feature or features were explicitly removed from the
.Nm NanoBSD
image when it was created.
.It
Everything is read-only at run-time.
It is safe to pull the power-plug.
There is no necessity to run
.Xr fsck 8
after a non-graceful shutdown of the system.
.It
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.
.El
.Ss Nm NanoBSD Ss Media Layout
The mass storage medium is divided into three parts by default (which
are normally mounted read-only):
.Pp
.Bl -bullet -offset indent -compact
.It
Two image partitions:
.Li code#1
and
.Li code#2 .
.It
The configuration file partition, which can be mounted under the
.Pa /cfg
directory at run time.
.El
.Pp
The
.Pa /etc
and
.Pa /var
directories are
.Xr md 4
(malloc backed) disks.
.Pp
The configuration file partition persists under the
.Pa /cfg
directory.
It contains files for
.Pa /etc
directory and is briefly mounted read-only right after the system boot,
therefore it is required to copy modified files from
.Pa /etc
back to the
.Pa /cfg
directory if changes are expected to persist after the system restarts.
.Sh BUILDING Nm NanoBSD
A
.Nm NanoBSD
image is built using a simple
.Nm
shell script, which can be
found in the
.Pa src/tools/tools/nanobsd
directory.
This script creates a bootable image, which can be copied on the storage
medium using the
.Xr dd 1
utility.
.Pp
The necessary commands to build and install a
.Nm NanoBSD
image are:
.Bd -literal -offset indent
cd /usr/src/tools/tools/nanobsd
sh nanobsd.sh
cd /usr/obj/nanobsd.full
dd if=_.disk.full of=/dev/da0 bs=64k
.Ed
.Sh CUSTOMIZING Nm NanoBSD
This is probably the most important and most interesting feature of
.Nm NanoBSD .
This is also where you will be spending most of the time when developing with
.Nm NanoBSD .
.Pp
Customization is done in two ways:
.Pp
.Bl -bullet -offset indent -compact
.It
Configuration options.
.It
Custom functions.
.El
.Pp
With configuration settings, it is possible to configure options passed
to both the
.Cm buildworld
and
.Cm installworld
stages of the
.Nm NanoBSD
build process, as well as internal options passed to the main build
process of
.Nm NanoBSD .
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 the system
even more, until it will consist of just the kernel and two or three
files in the userland.
.Pp
The configuration file consists of configuration options, which override
the default values.
The most important directives are:
.Bl -tag -width ".Va CONF_INSTALL" -offset indent
.It Va NANO_NAME
Build name (used to construct the working directory names).
.It Va NANO_SRC
Path to the source tree used to build the image.
.It Va NANO_KERNEL
Name of the kernel configuration file used to build the kernel.
.It Va NANO_ARCH
Machine processor architecture to build. Defaults to output of
.Cm uname -p .
.It Va NANO_BOOT0CFG
Controls the options passed to
.Xr boot0cfg 8 ;
these dictate
.Nm boot0 Ns 's
behaviour.
.It Va NANO_BOOTLOADER
The
.Nm boot0
loader to use relative to the
.Va NANO_WORLDDIR
variable.
This defaults to
.Pa boot/boot0sio
and should be overridden to
.Pa boot/boot0
to provide a VGA
console.
.It Va CONF_BUILD
Options passed to the
.Cm buildworld
stage of the build.
.It Va CONF_INSTALL
Options passed to the
.Cm installworld
stage of the build.
.It Va CONF_WORLD
Options passed to both the
.Cm buildworld
and
.Cm installworld
stages of the build.
.It Va FlashDevice
Defines the type of media to use.
Check the
.Pa FlashDevice.sub
file for more details.
.El
.Pp
For more configuration options, please check the
.Nm
script.
.Pp
To build
.Nm NanoBSD
image using the
.Pa nanobsd.conf
configuration file, use the following command:
.Bd -literal -offset indent
sh nanobsd.sh -c nanobsd.conf
.Ed
.Pp
It is possible to fine-tune
.Nm NanoBSD
using shell functions in the configuration file.
The following example illustrates the basic model of custom functions:
.Bd -literal -offset indent
cust_foo () (
	echo "bar=topless" > \\
	     ${NANO_WORLDDIR}/etc/foo
)
customize_cmd cust_foo
.Ed
.Pp
There are a few pre-defined customization functions ready for use:
.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
.It Cm cust_comconsole
Disables
.Xr getty 8
on the virtual
.Xr syscons 4
terminals
.Pq Pa /dev/ttyv*
and enables the use of the first serial port as the system
console.
.It Cm cust_allow_ssh_root
Allow root to log in via
.Xr sshd 8 .
.It Cm cust_install_files
Installs files from the
.Pa nanobsd/Files
directory, which contains some useful scripts for system administration.
.El
.Sh FILES
.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
.It Pa src/tools/tools/nanobsd
Base directory of the
.Nm NanoBSD
build script.
.El
.Sh EXAMPLES
Making persistent changes to
.Pa /etc/resolv.conf :
.Bd -literal -offset indent
vi /etc/resolv.conf
\&...
mount /cfg
cp /etc/resolv.conf /cfg
umount /cfg
.Ed
.Pp
A more useful example of a customization function is the following,
which changes the default size of the
.Pa /etc
directory from 5MB to 30MB:
.Bd -literal -offset indent
cust_etc_size () (
	cd ${NANO_WORLDDIR}/conf
	echo 30000 > default/etc/md_size
)
customize_cmd cust_etc_size
.Ed
.Sh SEE ALSO
.Xr make.conf 5 ,
.Xr boot 8 ,
.Xr boot0cfg 8 ,
.Xr picobsd 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 6.0 .
.Sh AUTHORS
.An -nosplit
.Nm NanoBSD
was developed by
.An Poul-Henning Kamp Aq phk@FreeBSD.org .
This manual page was written by
.An Daniel Gerzo Aq danger@FreeBSD.org .
OpenPOWER on IntegriCloud