/share/man/man8/nanobsd.8

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 337 lines · 337 code · 0 blank · 0 comment · 0 complexity · b6c26692269a108c9e84b8cc5b9fcc1b MD5 · raw file

  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 .