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