From 129518b229934710d0229349d4d99e1804e0e92e Mon Sep 17 00:00:00 2001 From: Daniel Gerzo Date: Tue, 29 Aug 2006 09:12:48 +0000 Subject: [PATCH] Add nanobsd(8) manual page. Reviewed by: ru Approved by: trhodes (mentor), keramida (mentor) MFC after: 1 week --- share/man/man8/Makefile | 1 + share/man/man8/nanobsd.8 | 308 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 309 insertions(+) create mode 100644 share/man/man8/nanobsd.8 diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile index 4c9678cd2ad7..2f5d1cf7744f 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 000000000000..264984bd1131 --- /dev/null +++ b/share/man/man8/nanobsd.8 @@ -0,0 +1,308 @@ +.\" Copyright (c) 2006 Daniel Gerzo +.\" 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 .