From danger@tomas.elvandar.org Mon Mar 13 19:22:09 2006 Return-Path: Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7D63116A42A for ; Mon, 13 Mar 2006 19:22:09 +0000 (UTC) (envelope-from danger@tomas.elvandar.org) Received: from tomas.elvandar.org (tomas.elvandar.org [217.148.169.60]) by mx1.FreeBSD.org (Postfix) with ESMTP id DAE2143D45 for ; Mon, 13 Mar 2006 19:22:08 +0000 (GMT) (envelope-from danger@tomas.elvandar.org) Received: by tomas.elvandar.org (Postfix, from userid 1002) id D7488483FB8; Mon, 13 Mar 2006 19:22:07 +0000 (UTC) Message-Id: <20060313192207.D7488483FB8@tomas.elvandar.org> Date: Mon, 13 Mar 2006 19:22:07 +0000 (UTC) From: Daniel Gerzo Reply-To: Daniel Gerzo To: FreeBSD-gnats-submit@freebsd.org Cc: Subject: [patch] NanoBSD chapter for Handbook X-Send-Pr-Version: 3.113 X-GNATS-Notify: >Number: 94419 >Category: docs >Synopsis: [patch] NanoBSD chapter for Handbook >Confidential: no >Severity: non-critical >Priority: low >Responsible: keramida >State: closed >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Mon Mar 13 19:30:06 GMT 2006 >Closed-Date: Thu May 04 16:22:40 GMT 2006 >Last-Modified: Thu May 04 16:22:40 GMT 2006 >Originator: Daniel Gerzo >Release: FreeBSD 6.1-PRERELEASE i386 >Organization: rulez.sk >Environment: System: FreeBSD tomas.elvandar.org 6.1-PRERELEASE FreeBSD 6.1-PRERELEASE #0: Wed Feb 15 02:22:30 CET 2006 root@redqueen.elvandar.org:/usr/obj/usr/src/sys/REDQUEEN i386 >Description: As the documentation of the NanoBSD in its project site on freebsd.org server is badly outdated and there is a Todo thing on this, I've been working to document this tool. Now it's mostly done and it needs review by some doc guy, most preferably native speaker. The document was OK'd by phk@ in a technical manner via IRC. The build version is available at: http://www.sk.freebsd.org/doc/en/books/handbook/nanobsd.html The source attached in Fix: section is also available at http://danger.rulez.sk/nanobsd.sgml >How-To-Repeat: >Fix: --- chapter.sgml begins here --- Daniel Gerzo Written by NanoBSD Introduction to <application>NanoBSD</application> NanoBSD is 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 probably be used to build a specialized server designed for easy installation and maintenance called computer applicance. Computer appliances have their hardware and software bundled in the product, so all applications are pre-installed. The appliance is plugged into an existing network and can begin working (almost) immediately. Features of NanoBSD: Ports and packages work like in &os;. No missing functionality — If it is possible to do with &os;, it is possible to do with NanoBSD, unless it was removed in compile time. Everything is read-only at run-time — It is safe to pull the power-plug. &man.fsck.8; is not necessary. Easy to build and customize. <application>NanoBSD</application> Howto The design of <application>NanoBSD</application> Once the image is present on the medium, it is possible to boot the NanoBSD. The mass storage medium is divided into three parts, two image partitions - code#1 and code#2, and the configuration file partition - /cfg, which are normally mounted read-only. This means that it is safe to pull the power plug on a NanoBSD machine and that Flash based storage is not worn out with file system metadata writes. /etc and /var directories are &man.md.4; (malloc) disks. The configuration file partition persists under the /cfg directory. This partition contains files for /etc directory and is briefly mounted read-only right after the system boot. Note that this partition should be mounted only at boot-time and while overriding the configuration files. After some modifications have been done in files in /etc and they are proposed to exist after next boot, it is required to copy them to the /cfg directory. For example: &prompt.root; vim /etc/resolv.conf [...] &prompt.root; mount /cfg &prompt.root; cp /etc/resolv.conf /cfg &prompt.root; umount /cfg Building <application>NanoBSD</application> images The NanoBSD is built using a simple nanobsd.sh 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; command. 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 Customizing <application>NanoBSD</application> images This is probably the most important and most interesting feature of NanoBSD. This is also place 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 buildworld and installworld 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 medium. If much time is spent here, it can be cut down even further, until it will consists of just the kernel and two or three files in the userland. 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. CONF_INSTALL — Options passed to the installworld. CONF_WORLD — Options passed to both buildworld and installworld. 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 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 More useful example of usage of custom functions can represent the following function, which changes the default size of /etc 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 ( /dev/ttyv*) and enables console in the COM1 serial port. cust_allow_ssh_root — Allow root to login via &man.sshd.8;. cust_install_files — Installs files from nanobsd/Files directory, which contains some useful scripts for system administration. Configuration file example The example of configuration file might be following: 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 <application>NanoBSD</application> Update of NanoBSD is very simple. This involves the steps of building NanoBSD image described above and installing it onto the partition. The only difference is that the _.disk.image image (which contains the system for only one partition) is used instead of _.disk.full. Having two image partitions means that it is possible to download a new image while the system is running, reboot to run that new image and if that fails somehow, it is still possible to switch back to the old image partition. 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. It is possible to exampine one of these three ways: Using &man.nc.1; myhost&prompt.root; nc -l 2222 < _.disk.image &prompt.root; nc myhost 2222 | sh updatep1 Using &man.ftp.1; &prompt.root; ftp myhost get _.disk.image "| sh updatep1" Using &man.ssh.1; &prompt.root; ssh myhost cat _.disk.image.gz | zcat | sh updatep1 --- chapter.sgml ends here --- >Release-Note: >Audit-Trail: From: "Jesus R. Camou" To: Daniel Gerzo Cc: FreeBSD-gnats-submit@FreeBSD.org Subject: Re: docs/94419: [patch] NanoBSD chapter for Handbook Date: Mon, 13 Mar 2006 19:56:05 +0000 An express review. On Mon, Mar 13, 2006 at 07:22:07PM +0000, Daniel Gerzo wrote: > > > > > > > Daniel > Gerzo > Written by > > > > > > NanoBSD > > > Introduction to <application>NanoBSD</application> > > NanoBSD is tool currently `a tool' > 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 probably be used to build a specialized server designed > for easy installation and maintenance called computer applicance. > Computer appliances have their hardware and software bundled in > the product, so all applications are pre-installed. The appliance s/so/which means/ perhaps? > is plugged into an existing network and can begin working (almost) > immediately. > > Features of NanoBSD: > > > > Ports and packages work like in &os;. Probably s/like/as/ or something, or rewrite the whole sentence. > > > No missing functionality — If it is possible to do > with &os;, it is possible to do with > NanoBSD, unless it was removed in > compile time. > > > Everything is read-only at run-time — It is safe to > pull the power-plug. &man.fsck.8; is not necessary. > > > Easy to build and customize. > > > > > > <application>NanoBSD</application> Howto > > > The design of <application>NanoBSD</application> > > Once the image is present on the medium, it is possible to > boot the NanoBSD. The mass storage ^^^ Remove `the' here. > medium is divided into three parts, two image partitions - > code#1 and code#2, and the > configuration file partition - > /cfg, which are normally > mounted read-only. This means that it is safe to pull the power > plug on a NanoBSD machine and that > Flash based storage is not worn out with file system metadata > writes. > > /etc and > /var directories are > &man.md.4; (malloc) disks. > > The configuration file partition persists under the role="directory">/cfg directory. This partition > contains files for /etc > directory and is briefly mounted read-only right after the system > boot. Note that this partition should be mounted only at > boot-time and while overriding the configuration files. > > After some modifications have been done in files in > /etc and they are proposed > to exist after next boot, it is required to copy them to the > /cfg directory. For ^^ Double space after dot. You may want to take a look at some of the sentences for possible redundancies or better sentence options. - j From: Daniel Gerzo To: FreeBSD-gnats-submit@FreeBSD.org Cc: "Jesus R. Camou" Subject: Re[2]: docs/94419: [patch] NanoBSD chapter for Handbook Date: Tue, 14 Mar 2006 13:12:31 +0000 Hello, I have fixed things you have pointed out (thanks) and rewritten some parts as well as updated the content a bit. New chapter.sgml is available at: http://danger.rulez.sk/nanobsd.sgml The built version is available at: http://www.sk.freebsd.org/doc/en/books/handbook/nanobsd.html -- Sincerely, Daniel Gerzo Responsible-Changed-From-To: freebsd-doc->keramida Responsible-Changed-By: keramida Responsible-Changed-When: Fri Apr 28 17:38:54 UTC 2006 Responsible-Changed-Why: I've imported the chapter by Daniel in my local tree, and also made some improvements with the help of Daniel and others from #bsddocs. To avoid duplicating this work I'll grab this PR and commit it into the tree after we have a new chapter draft ready (probably after the release of 6.1-REL, unless doceng@ approves of the change earlier). http://www.freebsd.org/cgi/query-pr.cgi?pr=94419 State-Changed-From-To: open->closed State-Changed-By: keramida State-Changed-When: Thu May 4 16:21:56 UTC 2006 State-Changed-Why: Committed, thanks! http://www.freebsd.org/cgi/query-pr.cgi?pr=94419 >Unformatted: