share/man/man8/nanobsd.8

   1 .\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd August 28, 2006
  28 .Dt NANOBSD 8
  29 .Os
  30 .Sh NAME
  31 .Nm nanobsd.sh
  32 .Nd utility used to create a FreeBSD system image suitable for embedded
  33 applications
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl bhkw
  37 .Op Fl c Ar config-file
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility is a script which produces a minimal implementation of
  42 .Fx
  43 (called
  44 .Nm NanoBSD ) ,
  45 which typically fits on a small media such as a Compact Flash card,
  46 or other mass storage medium.
  47 It can be used to build specialized install images, designed for easy
  48 installation and maintenance.
  49 .Pp
  50 The following options are available:
  51 .Bl -tag -width ".Fl c Ar config-file" -offset indent
  52 .It Fl b
  53 Skip the build stages (both for kernel and world).
  54 .It Fl c Ar config-file
  55 Specify the configuration file to use.
  56 .It Fl h
  57 Display usage information.
  58 .It Fl k
  59 Skip the
  60 .Cm buildkernel
  61 stage of the build.
  62 .It Fl w
  63 Skip the
  64 .Cm buildworld
  65 stage of the build.
  66 .El
  67 .Pp
  68 The features of
  69 .Nm NanoBSD
  70 include:
  71 .Pp
  72 .Bl -bullet -offset indent -compact
  73 .It
  74 Ports and packages work as in
  75 .Fx .
  76 Every single application can be installed and used in a
  77 .Nm NanoBSD
  78 image, the same way as in
  79 .Fx .
  80 .It
  81 No missing functionality.
  82 If it is possible to do something with
  83 .Fx ,
  84 it is possible to do the same thing with
  85 .Nm NanoBSD ,
  86 unless the specific feature or features were explicitly removed from the
  87 .Nm NanoBSD
  88 image when it was created.
  89 .It
  90 Everything is read-only at run-time.
  91 It is safe to pull the power-plug.
  92 There is no necessity to run
  93 .Xr fsck 8
  94 after a non-graceful shutdown of the system.
  95 .It
  96 Easy to build and customize.
  97 Making use of just one shell script and one configuration file it is
  98 possible to build reduced and customized images satisfying any arbitrary
  99 set of requirements.
 100 .El
 101 .Ss Nm NanoBSD Ss Media Layout
 102 The mass storage medium is divided into three parts by default (which
 103 are normally mounted read-only):
 104 .Pp
 105 .Bl -bullet -offset indent -compact
 106 .It
 107 Two image partitions:
 108 .Li code#1
 109 and
 110 .Li code#2 .
 111 .It
 112 The configuration file partition, which can be mounted under the
 113 .Pa /cfg
 114 directory at run time.
 115 .El
 116 .Pp
 117 The
 118 .Pa /etc
 119 and
 120 .Pa /var
 121 directories are
 122 .Xr md 4
 123 (malloc backed) disks.
 124 .Pp
 125 The configuration file partition persists under the
 126 .Pa /cfg
 127 directory.
 128 It contains files for
 129 .Pa /etc
 130 directory and is briefly mounted read-only right after the system boot,
 131 therefore it is required to copy modified files from
 132 .Pa /etc
 133 back to the
 134 .Pa /cfg
 135 directory if changes are expected to persist after the system restarts.
 136 .Sh BUILDING Nm NanoBSD
 137 A
 138 .Nm NanoBSD
 139 image is built using a simple
 140 .Nm
 141 shell script, which can be
 142 found in the
 143 .Pa src/tools/tools/nanobsd
 144 directory.
 145 This script creates a bootable image, which can be copied on the storage
 146 medium using the
 147 .Xr dd 1
 148 utility.
 149 .Pp
 150 The necessary commands to build and install a
 151 .Nm NanoBSD
 152 image are:
 153 .Bd -literal -offset indent
 154 cd /usr/src/tools/tools/nanobsd
 155 sh nanobsd.sh
 156 cd /usr/obj/nanobsd.full
 157 dd if=_.disk.full of=/dev/da0 bs=64k
 158 .Ed
 159 .Sh CUSTOMIZING Nm NanoBSD
 160 This is probably the most important and most interesting feature of
 161 .Nm NanoBSD .
 162 This is also where you will be spending most of the time when developing with
 163 .Nm NanoBSD .
 164 .Pp
 165 Customization is done in two ways:
 166 .Pp
 167 .Bl -bullet -offset indent -compact
 168 .It
 169 Configuration options.
 170 .It
 171 Custom functions.
 172 .El
 173 .Pp
 174 With configuration settings, it is possible to configure options passed
 175 to both the
 176 .Cm buildworld
 177 and
 178 .Cm installworld
 179 stages of the
 180 .Nm NanoBSD
 181 build process, as well as internal options passed to the main build
 182 process of
 183 .Nm NanoBSD .
 184 Through these options it is possible to cut the system down, so it will
 185 fit on as little as 64MB.
 186 You can use the configuration options to trim down the system
 187 even more, until it will consist of just the kernel and two or three
 188 files in the userland.
 189 .Pp
 190 The configuration file consists of configuration options, which override
 191 the default values.
 192 The most important directives are:
 193 .Bl -tag -width ".Va CONF_INSTALL" -offset indent
 194 .It Va NANO_NAME
 195 Build name (used to construct the working directory names).
 196 .It Va NANO_SRC
 197 Path to the source tree used to build the image.
 198 .It Va NANO_KERNEL
 199 Name of the kernel configuration file used to build the kernel.
 200 .It Va NANO_BOOT0CFG
 201 Controls the options passed to
 202 .Xr boot0cfg 8 ;
 203 these dictate
 204 .Nm boot0 Ns 's
 205 behaviour.
 206 .It Va NANO_BOOTLOADER
 207 The
 208 .Nm boot0
 209 loader to use relative to the
 210 .Va NANO_WORLDDIR
 211 variable.
 212 This defaults to
 213 .Pa boot/boot0sio
 214 and should be overridden to
 215 .Pa boot/boot0
 216 to provide a VGA
 217 console.
 218 .It Va CONF_BUILD
 219 Options passed to the
 220 .Cm buildworld
 221 stage of the build.
 222 .It Va CONF_INSTALL
 223 Options passed to the
 224 .Cm installworld
 225 stage of the build.
 226 .It Va CONF_WORLD
 227 Options passed to both the
 228 .Cm buildworld
 229 and
 230 .Cm installworld
 231 stages of the build.
 232 .It Va FlashDevice
 233 Defines the type of media to use.
 234 Check the
 235 .Pa FlashDevice.sub
 236 file for more details.
 237 .El
 238 .Pp
 239 For more configuration options, please check the
 240 .Nm
 241 script.
 242 .Pp
 243 To build
 244 .Nm NanoBSD
 245 image using the
 246 .Pa nanobsd.conf
 247 configuration file, use the following command:
 248 .Bd -literal -offset indent
 249 sh nanobsd.sh -c nanobsd.conf
 250 .Ed
 251 .Pp
 252 It is possible to fine-tune
 253 .Nm NanoBSD
 254 using shell functions in the configuration file.
 255 The following example illustrates the basic model of custom functions:
 256 .Bd -literal -offset indent
 257 cust_foo () (
 258         echo "bar=topless" > \\
 259              ${NANO_WORLDDIR}/etc/foo
 260 )
 261 customize_cmd cust_foo
 262 .Ed
 263 .Pp
 264 There are a few pre-defined customization functions ready for use:
 265 .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
 266 .It Cm cust_comconsole
 267 Disables
 268 .Xr getty 8
 269 on the virtual
 270 .Xr syscons 4
 271 terminals
 272 .Pq Pa /dev/ttyv*
 273 and enables the use of the first serial port as the system
 274 console.
 275 .It Cm cust_allow_ssh_root
 276 Allow root to log in via
 277 .Xr sshd 8 .
 278 .It Cm cust_install_files
 279 Installs files from the
 280 .Pa nanobsd/Files
 281 directory, which contains some useful scripts for system administration.
 282 .El
 283 .Sh FILES
 284 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
 285 .It Pa src/tools/tools/nanobsd
 286 Base directory of the
 287 .Nm NanoBSD
 288 build script.
 289 .El
 290 .Sh EXAMPLES
 291 Making persistent changes to
 292 .Pa /etc/resolv.conf :
 293 .Bd -literal -offset indent
 294 vi /etc/resolv.conf
 295 \&...
 296 mount /cfg
 297 cp /etc/resolv.conf /cfg
 298 umount /cfg
 299 .Ed
 300 .Pp
 301 A more useful example of a customization function is the following,
 302 which changes the default size of the
 303 .Pa /etc
 304 directory from 5MB to 30MB:
 305 .Bd -literal -offset indent
 306 cust_etc_size () (
 307         cd ${NANO_WORLDDIR}/conf
 308         echo 30000 > default/etc/md_size
 309 )
 310 customize_cmd cust_etc_size
 311 .Ed
 312 .Sh SEE ALSO
 313 .Xr make.conf 5 ,
 314 .Xr boot 8 ,
 315 .Xr boot0cfg 8 ,
 316 .Xr picobsd 8
 317 .Sh HISTORY
 318 The
 319 .Nm
 320 utility first appeared in
 321 .Fx 6.0 .
 322 .Sh AUTHORS
 323 .An -nosplit
 324 .Nm NanoBSD
 325 was developed by
 326 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
 327 This manual page was written by
 328 .An Daniel Gerzo Aq danger@FreeBSD.org .