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 March 16, 2009
  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 bhknw
  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 n
  63 Do not cleanup before each build stage.
  64 This suppresses the normal cleanup work done before the
  65 .Cm buildworld
  66 stage and adds -DNO_CLEAN to the make command line
  67 used for each build stage (world and kernel).
  68 .It Fl w
  69 Skip the
  70 .Cm buildworld
  71 stage of the build.
  72 .El
  73 .Pp
  74 The features of
  75 .Nm NanoBSD
  76 include:
  77 .Pp
  78 .Bl -bullet -offset indent -compact
  79 .It
  80 Ports and packages work as in
  81 .Fx .
  82 Every single application can be installed and used in a
  83 .Nm NanoBSD
  84 image, the same way as in
  85 .Fx .
  86 .It
  87 No missing functionality.
  88 If it is possible to do something with
  89 .Fx ,
  90 it is possible to do the same thing with
  91 .Nm NanoBSD ,
  92 unless the specific feature or features were explicitly removed from the
  93 .Nm NanoBSD
  94 image when it was created.
  95 .It
  96 Everything is read-only at run-time.
  97 It is safe to pull the power-plug.
  98 There is no necessity to run
  99 .Xr fsck 8
 100 after a non-graceful shutdown of the system.
 101 .It
 102 Easy to build and customize.
 103 Making use of just one shell script and one configuration file it is
 104 possible to build reduced and customized images satisfying any arbitrary
 105 set of requirements.
 106 .El
 107 .Ss Nm NanoBSD Ss Media Layout
 108 The mass storage medium is divided into three parts by default (which
 109 are normally mounted read-only):
 110 .Pp
 111 .Bl -bullet -offset indent -compact
 112 .It
 113 Two image partitions:
 114 .Li code#1
 115 and
 116 .Li code#2 .
 117 .It
 118 The configuration file partition, which can be mounted under the
 119 .Pa /cfg
 120 directory at run time.
 121 .El
 122 .Pp
 123 The
 124 .Pa /etc
 125 and
 126 .Pa /var
 127 directories are
 128 .Xr md 4
 129 (malloc backed) disks.
 130 .Pp
 131 The configuration file partition persists under the
 132 .Pa /cfg
 133 directory.
 134 It contains files for
 135 .Pa /etc
 136 directory and is briefly mounted read-only right after the system boot,
 137 therefore it is required to copy modified files from
 138 .Pa /etc
 139 back to the
 140 .Pa /cfg
 141 directory if changes are expected to persist after the system restarts.
 142 .Sh BUILDING Nm NanoBSD
 143 A
 144 .Nm NanoBSD
 145 image is built using a simple
 146 .Nm
 147 shell script, which can be
 148 found in the
 149 .Pa src/tools/tools/nanobsd
 150 directory.
 151 This script creates a bootable image, which can be copied on the storage
 152 medium using the
 153 .Xr dd 1
 154 utility.
 155 .Pp
 156 The necessary commands to build and install a
 157 .Nm NanoBSD
 158 image are:
 159 .Bd -literal -offset indent
 160 cd /usr/src/tools/tools/nanobsd
 161 sh nanobsd.sh
 162 cd /usr/obj/nanobsd.full
 163 dd if=_.disk.full of=/dev/da0 bs=64k
 164 .Ed
 165 .Sh CUSTOMIZING Nm NanoBSD
 166 This is probably the most important and most interesting feature of
 167 .Nm NanoBSD .
 168 This is also where you will be spending most of the time when developing with
 169 .Nm NanoBSD .
 170 .Pp
 171 Customization is done in two ways:
 172 .Pp
 173 .Bl -bullet -offset indent -compact
 174 .It
 175 Configuration options.
 176 .It
 177 Custom functions.
 178 .El
 179 .Pp
 180 With configuration settings, it is possible to configure options passed
 181 to both the
 182 .Cm buildworld
 183 and
 184 .Cm installworld
 185 stages of the
 186 .Nm NanoBSD
 187 build process, as well as internal options passed to the main build
 188 process of
 189 .Nm NanoBSD .
 190 Through these options it is possible to cut the system down, so it will
 191 fit on as little as 64MB.
 192 You can use the configuration options to trim down the system
 193 even more, until it will consist of just the kernel and two or three
 194 files in the userland.
 195 .Pp
 196 The configuration file consists of configuration options, which override
 197 the default values.
 198 The most important directives are:
 199 .Bl -tag -width ".Va CONF_INSTALL" -offset indent
 200 .It Va NANO_NAME
 201 Build name (used to construct the working directory names).
 202 .It Va NANO_SRC
 203 Path to the source tree used to build the image.
 204 .It Va NANO_KERNEL
 205 Name of the kernel configuration file used to build the kernel.
 206 .It Va NANO_BOOT0CFG
 207 Controls the options passed to
 208 .Xr boot0cfg 8 ;
 209 these dictate
 210 .Nm boot0 Ns 's
 211 behaviour.
 212 .It Va NANO_BOOTLOADER
 213 The
 214 .Nm boot0
 215 loader to use relative to the
 216 .Va NANO_WORLDDIR
 217 variable.
 218 This defaults to
 219 .Pa boot/boot0sio
 220 and should be overridden to
 221 .Pa boot/boot0
 222 to provide a VGA
 223 console.
 224 .It Va CONF_BUILD
 225 Options passed to the
 226 .Cm buildworld
 227 stage of the build.
 228 .It Va CONF_INSTALL
 229 Options passed to the
 230 .Cm installworld
 231 stage of the build.
 232 .It Va CONF_WORLD
 233 Options passed to both the
 234 .Cm buildworld
 235 and
 236 .Cm installworld
 237 stages of the build.
 238 .It Va FlashDevice
 239 Defines the type of media to use.
 240 Check the
 241 .Pa FlashDevice.sub
 242 file for more details.
 243 .El
 244 .Pp
 245 For more configuration options, please check the
 246 .Nm
 247 script.
 248 .Pp
 249 To build
 250 .Nm NanoBSD
 251 image using the
 252 .Pa nanobsd.conf
 253 configuration file, use the following command:
 254 .Bd -literal -offset indent
 255 sh nanobsd.sh -c nanobsd.conf
 256 .Ed
 257 .Pp
 258 It is possible to fine-tune
 259 .Nm NanoBSD
 260 using shell functions in the configuration file.
 261 The following example illustrates the basic model of custom functions:
 262 .Bd -literal -offset indent
 263 cust_foo () (
 264         echo "bar=topless" > \\
 265              ${NANO_WORLDDIR}/etc/foo
 266 )
 267 customize_cmd cust_foo
 268 .Ed
 269 .Pp
 270 There are a few pre-defined customization functions ready for use:
 271 .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
 272 .It Cm cust_comconsole
 273 Disables
 274 .Xr getty 8
 275 on the virtual
 276 .Xr syscons 4
 277 terminals
 278 .Pq Pa /dev/ttyv*
 279 and enables the use of the first serial port as the system
 280 console.
 281 .It Cm cust_allow_ssh_root
 282 Allow root to log in via
 283 .Xr sshd 8 .
 284 .It Cm cust_install_files
 285 Installs files from the
 286 .Pa nanobsd/Files
 287 directory, which contains some useful scripts for system administration.
 288 .El
 289 .Sh FILES
 290 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
 291 .It Pa src/tools/tools/nanobsd
 292 Base directory of the
 293 .Nm NanoBSD
 294 build script.
 295 .El
 296 .Sh EXAMPLES
 297 Making persistent changes to
 298 .Pa /etc/resolv.conf :
 299 .Bd -literal -offset indent
 300 vi /etc/resolv.conf
 301 \&...
 302 mount /cfg
 303 cp /etc/resolv.conf /cfg
 304 umount /cfg
 305 .Ed
 306 .Pp
 307 A more useful example of a customization function is the following,
 308 which changes the default size of the
 309 .Pa /etc
 310 directory from 5MB to 30MB:
 311 .Bd -literal -offset indent
 312 cust_etc_size () (
 313         cd ${NANO_WORLDDIR}/conf
 314         echo 30000 > default/etc/md_size
 315 )
 316 customize_cmd cust_etc_size
 317 .Ed
 318 .Sh SEE ALSO
 319 .Xr make.conf 5 ,
 320 .Xr boot 8 ,
 321 .Xr boot0cfg 8 ,
 322 .Xr picobsd 8
 323 .Sh HISTORY
 324 The
 325 .Nm
 326 utility first appeared in
 327 .Fx 6.0 .
 328 .Sh AUTHORS
 329 .An -nosplit
 330 .Nm NanoBSD
 331 was developed by
 332 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
 333 This manual page was written by
 334 .An Daniel Gerzo Aq danger@FreeBSD.org .