From c596778b63aa024e0e9dc58ba6172ccc8502f2d4 Mon Sep 17 00:00:00 2001 From: Giorgos Keramidas Date: Tue, 16 May 2006 13:58:44 +0000 Subject: [PATCH] Convert the "NanoBSD" Handbook chapter to an article. Requested by: blackend, hrs --- en_US.ISO8859-1/articles/Makefile | 1 + en_US.ISO8859-1/articles/nanobsd/Makefile | 19 + en_US.ISO8859-1/articles/nanobsd/article.sgml | 489 ++++++++++++++++++ 3 files changed, 509 insertions(+) create mode 100644 en_US.ISO8859-1/articles/nanobsd/Makefile create mode 100644 en_US.ISO8859-1/articles/nanobsd/article.sgml diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile index e0b1983b5c..f5afc9770b 100644 --- a/en_US.ISO8859-1/articles/Makefile +++ b/en_US.ISO8859-1/articles/Makefile @@ -31,6 +31,7 @@ SUBDIR+= linux-comparison SUBDIR+= mailing-list-faq SUBDIR+= mh SUBDIR+= multi-os +SUBDIR+= nanobsd SUBDIR+= new-users SUBDIR+= p4-primer SUBDIR+= pam diff --git a/en_US.ISO8859-1/articles/nanobsd/Makefile b/en_US.ISO8859-1/articles/nanobsd/Makefile new file mode 100644 index 0000000000..27e137e845 --- /dev/null +++ b/en_US.ISO8859-1/articles/nanobsd/Makefile @@ -0,0 +1,19 @@ +# +# $FreeBSD$ +# +# Article: Introduction to NanoBSD + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/nanobsd/article.sgml b/en_US.ISO8859-1/articles/nanobsd/article.sgml new file mode 100644 index 0000000000..007d3b7995 --- /dev/null +++ b/en_US.ISO8859-1/articles/nanobsd/article.sgml @@ -0,0 +1,489 @@ + +%articles.ent; +]> + +
+ + Introduction to NanoBSD + + + + Daniel + Gerzo + + + + + $FreeBSD$ + + + 2006 + The FreeBSD Documentation Project + + + + &tm-attrib.freebsd; + &tm-attrib.general; + + + + This document provides information about + the NanoBSD tools, which can be used to + create &os; system images for embedded applications, suitable for + use on a Compact Flash card (or other mass storage medium). + + + + + Introduction to NanoBSD + + NanoBSD + + NanoBSD is a tool currently + developed by &a.phk;. It creates a &os; system image for embedded + applications, suitable for use on a Compact Flash card (or other + mass storage medium). + + It can be used to build specialized install images, designed for + easy installation and maintenance of systems commonly + called computer appliances. Computer appliances have + their hardware and software bundled in the product, which means all + applications are pre-installed. The appliance is plugged into an + existing network and can begin working (almost) immediately. + + The features of NanoBSD include: + + + + Ports and packages work as in &os; — Every single + application can be installed and used in + a NanoBSD image, the same way as in + &os;. + + + + No missing functionality — If it is possible to do + something with &os;, it is possible to do the same thing with + NanoBSD, unless the specific feature + or features were explicitly removed from + the NanoBSD image when it was + created. + + + + Everything is read-only at run-time — It is safe to + pull the power-plug. There is no necessity to run + &man.fsck.8; after a non-graceful shutdown of the system. + + + + 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. + + + + + + NanoBSD Howto + + + The design of NanoBSD + + Once the image is present on the medium, it is possible to + boot NanoBSD. The mass storage + medium is divided into three parts by default: + + + + Two image partitions: code#1 + and code#2. + + + + The configuration file partition, which can be mounted + under the /cfg directory + at run time. + + + + These partitions are normally mounted read-only. + + The /etc and + /var directories are + &man.md.4; (malloc) disks. + + The configuration file partition persists under the + /cfg directory. It + contains files for /etc + directory and is briefly mounted read-only right after the + system boot, therefore it is required to copy modified files + from /etc back to the + /cfg directory if changes + are expected to persist after the system restarts. + + + Making persistent changes to <filename>/etc/resolv.conf</filename> + + &prompt.root; vi /etc/resolv.conf +[...] +&prompt.root; mount /cfg +&prompt.root; cp /etc/resolv.conf /cfg +&prompt.root; umount /cfg + + + + The partition containing + /cfg should be mounted + only at boot time and while overriding the configuration + files. + + Keeping /cfg mounted at + all times is not a good idea, especially if + the NanoBSD system runs off a mass + storage medium that may be adversely affected by a large number + of writes to the partition (i.e. when the filesystem syncer + flushes data to the system disks). + + + + + Building a NanoBSD image + + A NanoBSD image is built using a + simple nanobsd.sh shell script, which can + be found in the + /usr/src/tools/tools/nanobsd + directory. This script creates an image, which can be copied on + the storage medium using the &man.dd.1; utility. + + The necessary commands to build a + NanoBSD image are: + + &prompt.root; cd /usr/src/tools/tools/nanobsd +&prompt.root; sh nanobsd.sh +&prompt.root; cd /usr/obj/nanobsd.full +&prompt.root; dd if=_.disk.full of=/dev/da0 bs=64k + + + + Change the current directory to the base directory of the + NanoBSD build script. + + + + Start the build process. + + + + Change the current directory to the place where the built + images are located. + + + + Install NanoBSD onto the + storage medium. + + + + + + Customizing a NanoBSD image + + This is probably the most important and most interesting + feature of NanoBSD. This is also + where you will be spending most of the time when + developing with NanoBSD. + + Invocation of the following command will force the + nanobsd.sh to read its configuration from + the myconf.nano file located in the current + directory: + + &prompt.root; sh nanobsd.sh -c myconf.nano + + Customization is done in two ways: + + + + Configuration options + + + + Custom functions + + + + + Configuration options + + With configuration settings, it is possible to configure options + passed to both the buildworld + and installworld stages of the + NanoBSD build process, as well as internal + options passed to the main build process of + 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 &os; even + more, until it will consists of just the kernel and two or three + files in the userland. + + The configuration file consists of configuration options, + which override the default values. The most important + directives are: + + + + NANO_NAME — Name of build + (used to construct the workdir names). + + + + NANO_SRC — Path to the source + tree used to build the image. + + + + NANO_KERNEL — Name of kernel + configuration file used to build kernel. + + + + CONF_BUILD — Options passed + to the buildworld stage of the build. + + + + CONF_INSTALL — Options passed + to the installworld stage of the build. + + + + CONF_WORLD — Options passed to both + the buildworld and + the installworld stage of the build. + + + + FlashDevice — Defines what type of + media to use. Check the FlashDevice.sub + file for more details. + + + + + + Custom functions + + It is possible to fine-tune + NanoBSD using shell functions in + the configuration file. The following example illustrates the + basic model of custom functions: + + cust_foo () ( + echo "bar=topless" > \ + ${NANO_WORLDDIR}/etc/foo +) +customize_cmd cust_foo + + A more useful example of a customization function is the + following, which changes the default size of the + /etc directory + from 5MB to 30MB: + + cust_etc_size () ( + cd ${NANO_WORLDDIR}/conf + echo 30000 > default/etc/md_size +) +customize_cmd cust_etc_size + + There are a few default pre-defined customization functions + ready for use: + + + + cust_comconsole — Disables + &man.getty.8; on the VGA devices + (the /dev/ttyv* device nodes) and enables + the use of the COM1 serial port as the system console. + + + + cust_allow_ssh_root — Allow + root to login via &man.sshd.8;. + + + + cust_install_files — + Installs files from the + nanobsd/Files + directory, which contains some useful scripts for system + administration. + + + + + + Configuration file example + + A complete example of a configuration file for building a + custom NanoBSD image can be: + + NANO_NAME=custom +NANO_SRC=/usr/src +NANO_KERNEL=MYKERNEL +NANO_IMAGES=2 + +CONF_BUILD=' +NO_KLDLOAD=YES +NO_NETGRAPH=YES +NO_PAM=YES +' + +CONF_INSTALL=' +NO_ACPI=YES +NO_BLUETOOTH=YES +NO_CVS=YES +NO_FORTRAN=YES +NO_HTML=YES +NO_LPR=YES +NO_MAN=YES +NO_SENDMAIL=YES +NO_SHAREDOCS=YES +NO_EXAMPLES=YES +NO_INSTALLLIB=YES +NO_CALENDAR=YES +NO_MISC=YES +NO_SHARE=YES +' + +CONF_WORLD=' +NO_BIND=YES +NO_MODULES=YES +NO_KERBEROS=YES +NO_GAMES=YES +NO_RESCUE=YES +NO_LOCALES=YES +NO_SYSCONS=YES +NO_INFO=YES +' + +FlashDevice SanDisk 1G + +cust_nobeastie() ( + touch ${NANO_WORLDDIR}/boot/loader.conf + echo "beastie_disable=\"YES\"" >> ${NANO_WORLDDIR}/boot/loader.conf +) + +customize_cmd cust_comconsole +customize_cmd cust_install_files +customize_cmd cust_allow_ssh_root +customize_cmd cust_nobeastie + + + + + Updating NanoBSD + + The update process of NanoBSD is + relatively simple: + + + + Build a new NanoBSD image, as + usual. + + + + Upload the new image into an unused partition of a + running NanoBSD appliance. + + The most important difference of this step from the + initial NanoBSD installation is that + now instead of using the _.disk.full file + (which contains an image of the entire disk), + the _.disk.image image is installed (which + contains an image of a single system partition). + + + + Reboot, and start the system from the newly installed + partition. + + + + If all goes well, the upgrade is finished. + + + + If anything goes wrong, reboot back into the previous + partition (which contains the old, working image), to restore system + functionality as fast as possible. Fix any problems of the new + build, and repeat the process. + + + + To install new image onto the running + NanoBSD system, it is possible to use + either the updatep1 or + updatep2 script located in the + /root directory, depending + from which partition is running the current system. + + According to which services are available on host serving + new NanoBSD image and what type of + transfer is prefered, it is possible to examine one of these + three ways: + + + Using &man.ftp.1; + + If the transfer speed is in first place, use this + example: + + &prompt.root; ftp myhost +get _.disk.image "| sh updatep1" + + + + Using &man.ssh.1; + + If a secure transfer is prefered, consider using this + example: + + &prompt.root; ssh myhost cat _.disk.image.gz | zcat | sh updatep1 + + + + Using &man.nc.1; + + Try this example if the remote host is not running neither + &man.ftp.1; or &man.sshd.8; service: + + + + At first, open a TCP listener on host serving the + image and make it send the image to client: + + myhost&prompt.root; nc -l 2222 < _.disk.image + + + Make sure that the used port is not blocked to + receive incomming connections from + NanoBSD host by + firewall. + + + + Connect to the host serving new image and execute + updatep1 script: + + &prompt.root; nc myhost 2222 | sh updatep1 + + + + + +