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 May 20, 2010
  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_ARCH
 207 Machine processor architecture to build. Defaults to output of
 208 .Cm uname -p .
 209 .It Va NANO_BOOT0CFG
 210 Controls the options passed to
 211 .Xr boot0cfg 8 ;
 212 these dictate
 213 .Nm boot0 Ns 's
 214 behaviour.
 215 .It Va NANO_BOOTLOADER
 216 The
 217 .Nm boot0
 218 loader to use relative to the
 219 .Va NANO_WORLDDIR
 220 variable.
 221 This defaults to
 222 .Pa boot/boot0sio
 223 and should be overridden to
 224 .Pa boot/boot0
 225 to provide a VGA
 226 console.
 227 .It Va CONF_BUILD
 228 Options passed to the
 229 .Cm buildworld
 230 stage of the build.
 231 .It Va CONF_INSTALL
 232 Options passed to the
 233 .Cm installworld
 234 stage of the build.
 235 .It Va CONF_WORLD
 236 Options passed to both the
 237 .Cm buildworld
 238 and
 239 .Cm installworld
 240 stages of the build.
 241 .It Va FlashDevice
 242 Defines the type of media to use.
 243 Check the
 244 .Pa FlashDevice.sub
 245 file for more details.
 246 .El
 247 .Pp
 248 For more configuration options, please check the
 249 .Nm
 250 script.
 251 .Pp
 252 To build
 253 .Nm NanoBSD
 254 image using the
 255 .Pa nanobsd.conf
 256 configuration file, use the following command:
 257 .Bd -literal -offset indent
 258 sh nanobsd.sh -c nanobsd.conf
 259 .Ed
 260 .Pp
 261 It is possible to fine-tune
 262 .Nm NanoBSD
 263 using shell functions in the configuration file.
 264 The following example illustrates the basic model of custom functions:
 265 .Bd -literal -offset indent
 266 cust_foo () (
 267         echo "bar=topless" > \\
 268              ${NANO_WORLDDIR}/etc/foo
 269 )
 270 customize_cmd cust_foo
 271 .Ed
 272 .Pp
 273 There are a few pre-defined customization functions ready for use:
 274 .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
 275 .It Cm cust_comconsole
 276 Disables
 277 .Xr getty 8
 278 on the virtual
 279 .Xr syscons 4
 280 terminals
 281 .Pq Pa /dev/ttyv*
 282 and enables the use of the first serial port as the system
 283 console.
 284 .It Cm cust_allow_ssh_root
 285 Allow root to log in via
 286 .Xr sshd 8 .
 287 .It Cm cust_install_files
 288 Installs files from the
 289 .Pa nanobsd/Files
 290 directory, which contains some useful scripts for system administration.
 291 .El
 292 .Sh FILES
 293 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
 294 .It Pa src/tools/tools/nanobsd
 295 Base directory of the
 296 .Nm NanoBSD
 297 build script.
 298 .El
 299 .Sh EXAMPLES
 300 Making persistent changes to
 301 .Pa /etc/resolv.conf :
 302 .Bd -literal -offset indent
 303 vi /etc/resolv.conf
 304 \&...
 305 mount /cfg
 306 cp /etc/resolv.conf /cfg
 307 umount /cfg
 308 .Ed
 309 .Pp
 310 A more useful example of a customization function is the following,
 311 which changes the default size of the
 312 .Pa /etc
 313 directory from 5MB to 30MB:
 314 .Bd -literal -offset indent
 315 cust_etc_size () (
 316         cd ${NANO_WORLDDIR}/conf
 317         echo 30000 > default/etc/md_size
 318 )
 319 customize_cmd cust_etc_size
 320 .Ed
 321 .Sh SEE ALSO
 322 .Xr make.conf 5 ,
 323 .Xr boot 8 ,
 324 .Xr boot0cfg 8 ,
 325 .Xr picobsd 8
 326 .Sh HISTORY
 327 The
 328 .Nm
 329 utility first appeared in
 330 .Fx 6.0 .
 331 .Sh AUTHORS
 332 .An -nosplit
 333 .Nm NanoBSD
 334 was developed by
 335 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
 336 This manual page was written by
 337 .An Daniel Gerzo Aq danger@FreeBSD.org .