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