Add nanobsd(8) manual page.
Reviewed by: ru Approved by: trhodes (mentor), keramida (mentor) MFC after: 1 week
This commit is contained in:
danger
parent
8b1d56c480
commit
978dd12712
@ -6,6 +6,7 @@ MAN= adding_user.8 \
|
||||
diskless.8 \
|
||||
intro.8 \
|
||||
MAKEDEV.8 \
|
||||
nanobsd.8 \
|
||||
picobsd.8 \
|
||||
rc.8 \
|
||||
rc.sendmail.8 \
|
||||
|
||||
308
share/man/man8/nanobsd.8
Normal file
308
share/man/man8/nanobsd.8
Normal file
@ -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 .
|
||||
Loading…
Reference in New Issue
Block a user