Add nanobsd(8) manual page.

Reviewed by: ru
Approved by: trhodes (mentor), keramida (mentor)
MFC after: 1 week

2 files changed, 309 insertions, 0 deletions

diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile
index 4c9678c..2f5d1cf 100644
--- a/share/man/man8/Makefile
+++ b/share/man/man8/Makefile
@@ -6,6 +6,7 @@ MAN=	adding_user.8 \
 	diskless.8 \
 	intro.8 \
 	MAKEDEV.8 \
+	nanobsd.8 \
 	picobsd.8 \
 	rc.8 \
 	rc.sendmail.8 \
diff --git a/share/man/man8/nanobsd.8 b/share/man/man8/nanobsd.8
new file mode 100644
index 0000000..264984b
--- /dev/null
+++ b/share/man/man8/nanobsd.8
@@ -0,0 +1,308 @@
+.\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd August 28, 2006
+.Dt NANOBSD 8
+.Os
+.Sh NAME
+.Nm nanobsd.sh
+.Nd utility used to create a FreeBSD system image suitable for embedded
+applications
+.Sh SYNOPSIS
+.Nm
+.Op Fl bhkw
+.Op Fl c Ar config-file
+.Sh DESCRIPTION
+The
+.Nm
+utility is a script which produces a minimal implementation of
+.Fx
+(called
+.Nm NanoBSD ) ,
+which typically fits on a small media such as a Compact Flash card,
+or other mass storage medium.
+It can be used to build specialized install images, designed for easy
+installation and maintenance.
+.Pp
+The following options are available:
+.Bl -tag -width ".Fl c Ar config-file" -offset indent
+.It Fl b
+Skip the build stages (both for kernel and world).
+.It Fl c Ar config-file
+Specify the configuration file to use.
+.It Fl h
+Display usage information.
+.It Fl k
+Skip the
+.Cm buildkernel
+stage of the build.
+.It Fl w
+Skip the
+.Cm buildworld
+stage of the build.
+.El
+.Pp
+The features of
+.Nm NanoBSD
+include:
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+Ports and packages work as in
+.Fx .
+Every single application can be installed and used in a
+.Nm NanoBSD
+image, the same way as in
+.Fx .
+.It
+No missing functionality.
+If it is possible to do something with
+.Fx ,
+it is possible to do the same thing with
+.Nm NanoBSD ,
+unless the specific feature or features were explicitly removed from the
+.Nm NanoBSD
+image when it was created.
+.It
+Everything is read-only at run-time.
+It is safe to pull the power-plug.
+There is no necessity to run
+.Xr fsck 8
+after a non-graceful shutdown of the system.
+.It
+Easy to build and customize.
+Making use of just one shell script and one configuration file it is
+possible to build reduced and customized images satisfying any arbitrary
+set of requirements.
+.El
+.Ss Nm NanoBSD Ss Media Layout
+The mass storage medium is divided into three parts by default (which
+are normally mounted read-only):
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+Two image partitions:
+.Li code#1
+and
+.Li code#2 .
+.It
+The configuration file partition, which can be mounted under the
+.Pa /cfg
+directory at run time.
+.El
+.Pp
+The
+.Pa /etc
+and
+.Pa /var
+directories are
+.Xr md 4
+(malloc backed) disks.
+.Pp
+The configuration file partition persists under the
+.Pa /cfg
+directory.
+It contains files for
+.Pa /etc
+directory and is briefly mounted read-only right after the system boot,
+therefore it is required to copy modified files from
+.Pa /etc
+back to the
+.Pa /cfg
+directory if changes are expected to persist after the system restarts.
+.Sh BUILDING Nm NanoBSD
+A
+.Nm NanoBSD
+image is built using a simple
+.Nm
+shell script, which can be
+found in the
+.Pa src/tools/tools/nanobsd
+directory.
+This script creates a bootable image, which can be copied on the storage
+medium using the
+.Xr dd 1
+utility.
+.Pp
+The necessary commands to build and install a
+.Nm NanoBSD
+image are:
+.Bd -literal -offset indent
+cd /usr/src/tools/tools/nanobsd
+sh nanobsd.sh
+cd /usr/obj/nanobsd.full
+dd if=_.disk.full of=/dev/da0 bs=64k
+.Ed
+.Sh CUSTOMIZING Nm NanoBSD
+This is probably the most important and most interesting feature of
+.Nm NanoBSD .
+This is also where you will be spending most of the time when developing with
+.Nm NanoBSD .
+.Pp
+Customization is done in two ways:
+.Pp
+.Bl -bullet -offset indent -compact
+.It
+Configuration options.
+.It
+Custom functions.
+.El
+.Pp
+With configuration settings, it is possible to configure options passed
+to both the
+.Cm buildworld
+and
+.Cm installworld
+stages of the
+.Nm NanoBSD
+build process, as well as internal options passed to the main build
+process of
+.Nm NanoBSD .
+Through these options it is possible to cut the system down, so it will
+fit on as little as 64MB.
+You can use the configuration options to trim down the system
+even more, until it will consist of just the kernel and two or three
+files in the userland.
+.Pp
+The configuration file consists of configuration options, which override
+the default values.
+The most important directives are:
+.Bl -tag -width ".Va CONF_INSTALL" -offset indent
+.It Va NANO_NAME
+Build name (used to construct the working directory names).
+.It Va NANO_SRC
+Path to the source tree used to build the image.
+.It Va NANO_KERNEL
+Name of the kernel configuration file used to build the kernel.
+.It Va CONF_BUILD
+Options passed to the
+.Cm buildworld
+stage of the build.
+.It Va CONF_INSTALL
+Options passed to the
+.Cm installworld
+stage of the build.
+.It Va CONF_WORLD
+Options passed to both the
+.Cm buildworld
+and
+.Cm installworld
+stages of the build.
+.It Va FlashDevice
+Defines the type of media to use.
+Check the
+.Pa FlashDevice.sub
+file for more details.
+.El
+.Pp
+For more configuration options, please check the
+.Nm
+script.
+.Pp
+To build
+.Nm NanoBSD
+image using the
+.Pa nanobsd.conf
+configuration file, use the following command:
+.Bd -literal -offset indent
+sh nanobsd.sh -c nanobsd.conf
+.Ed
+.Pp
+It is possible to fine-tune
+.Nm NanoBSD
+using shell functions in the configuration file.
+The following example illustrates the basic model of custom functions:
+.Bd -literal -offset indent
+cust_foo () (
+	echo "bar=topless" > \\
+	     ${NANO_WORLDDIR}/etc/foo
+)
+customize_cmd cust_foo
+.Ed
+.Pp
+There are a few pre-defined customization functions ready for use:
+.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
+.It Cm cust_comconsole
+Disables
+.Xr getty 8
+on the virtual
+.Xr syscons 4
+terminals
+.Pq Pa /dev/ttyv*
+and enables the use of the first serial port as the system
+console.
+.It Cm cust_allow_ssh_root
+Allow root to log in via
+.Xr sshd 8 .
+.It Cm cust_install_files
+Installs files from the
+.Pa nanobsd/Files
+directory, which contains some useful scripts for system administration.
+.El
+.Sh FILES
+.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
+.It Pa src/tools/tools/nanobsd
+base directory of the
+.Nm NanoBSD
+build script.
+.El
+.Sh EXAMPLES
+Making persistent changes to
+.Pa /etc/resolv.conf :
+.Bd -literal -offset indent
+vi /etc/resolv.conf
+\&...
+mount /cfg
+cp /etc/resolv.conf /cfg
+umount /cfg
+.Ed
+.Pp
+A more useful example of a customization function is the following,
+which changes the default size of the
+.Pa /etc
+directory from 5MB to 30MB:
+.Bd -literal -offset indent
+cust_etc_size () (
+	cd ${NANO_WORLDDIR}/conf
+	echo 30000 > default/etc/md_size
+)
+customize_cmd cust_etc_size
+.Ed
+.Sh SEE ALSO
+.Xr make.conf 5 ,
+.Xr picobsd 8
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Fx 6.0 .
+.Sh AUTHORS
+.An -nosplit
+.Nm NanoBSD
+was developed by
+.An Poul-Henning Kamp Aq phk@FreeBSD.org .
+This manual page was written by
+.An Daniel Gerzo Aq danger@FreeBSD.org .