[Voyage-linux] A tool to install Voyage-boxes via PXE: jra-initrd

Tue Jan 13 01:22:29 HKT 2009

I mentioned earlier that I had made a system to let me automatically
partition, install, and setup grub on Alix devices without taking out
the CF Card. I like this because I am a software guy, not a hardware
guy. I don't like to open the box to install a new version of Voyage.
I prefer to reboot with PXE, install, and reboot with my new CF flash
image.

As a side-effect/bonus, this stuff has built into it my ideas about
how an emedded device should be partitioned (in these days of cheap,
big CF cards). It has a config-only partition, the normal root, the
failsafe root, and the rest of the CF card for data storage. See the
notes at the end of the README.

You can find it here:    http://nella.org/jra/geek/jra-initrd

The README is appended to this mail, so you can get a feel for it at a glance.

  -jeff

-- snip --

Notes on what this stuff is, how it works
=========================================

This is a system to generate an initrd. This initrd is the
ram disk mounted during a PXE boot. Currently, it includes
these features:

	* partition the CF card like this
		20 megs for grub and non-volatile stuff
		200 megs for root1
		200 megs for root2
		rest for data
	* install your voyage-XXX directory via rsync (easy, fast
		updating during development)
	* setup Grub

Here are features it can support in the future:
	* capture an image of a finished device
	* install an image (fast install for manufacturing many boxes
		with the same config)
	* make and install a per-device RSA key

This is a heavily modified version of bit-pxe, which in
turn is a wrapper and customization layer on top of mkinitramfs,
a standard Linux tool.

How to setup
------------

You need several new packages installed:

	apt-get install debootstrap
	apt-get install dnsmasq-base
	apt-get install rsync
	apt-get install openbsd-inetd
	apt-get install syslinux

You need to copy the Voyage kernel modules onto the machine used
to build the initrd:

	cp -r voyage-0.5.2/lib/modules/2.6.23-486-voyage /lib/modules

As the kernel version in Voyage is upgraded, the modules
need to be copied over again, and the kern= environment variable
need to be changed again.

How to build
------------

The sole output of this directory is an initrd.gz file (which is
itself a gziped cpio archive).

Here's the command to make it:
	kern=2.6.23-486-voyage sh build.sh

To install it:
	cp initrd.gz /var/tftp

Setup /var/tftp
---------------

dnsmasq, when run with the wrapper script, will use /var/tftp
as the root for the TFTP server (assuming voyage-0.5.2 is in $HOME).

	mkdir /var/tftp
	cd /var/tftp
	cp /usr/lib/syslinux/pxelinux.0 .
	cp $HOME/voyage-0.5.2/vmlinuz-2.6.23-486-voyage .
	ln -s vmlinuz-2.6.23-486-voyage linux
	mkdir pxelinux.cfg

Put a file like this into pxelinux.cfg/default:

  serial 0 38400
  console 0
  label linux
    KERNEL linux
    APPEND initrd=initrd.gz console=ttyS0,38400n1 root=/dev/hda1

If you want different configs for different machines, see
/usr/share/doc/syslinux/pxelinux.txt.gz for what filename to
use. Often the best choice is the hardware type and MAC address
in a format like this: 01-00-0d-b9-14-33-c8

How to run it
-------------

To boot via PXE:

1. Set a static IP address on your eth0 interface. You should use
   10.0.0.1, netmask 255.255.255.0 (no router) if possible. You
   can leave your wifi interface enabled and connected, with an
   IP address and the default route for your machine. It will
   route the 10.0.0.0/24 stuff out the wired ethernet only.

2. Check run-dnsmasq:
    * adjust for your static IP, if you could not use the one
      mentioned above.

3. Setup rsyncd according to the rsyncd.conf man page (search
   for "nowait" to see the right part). Ensure inetd is running.
   Here is an example rsyncd.conf file:

     [voyage]
       path = [the full path to your voyage-0.5.2 directory, or
		to your customized voyage root]
       use chroot = no
       max connections = 4
       uid = root
       gid = root
       read only = true

4. Run run-dnsmasq in one window.

5. Run minicom -s in another window. Set the serial port (usually
   /dev/ttyUSB0 or /dev/ttyS0) and the speed (38400-8-n-1).

6. Hook up the ALIX box, ethernet nearest the USB. Hook
   up the serial port.

7. Power up the ALIX, immediately type "S" (no quotes) while the
   memory check happens. Type "e" for PXE boot. Save and exit.

8. Watch it boot. Smile.

When the device is installed, turn off PXE boot ("S", "e", save and exit).

How to control it
-----------------

The scripts that run after the kernel boots take their input
from the boot arguments. See README.bit-pxe for boot flags you can use
to control it.

How to hack it
--------------

The main work happens here:

	linux/initramfs-tools/scripts/local-top/
		params
			If you add something to the boot cmdline, add it here too.
		disk
			Partitioning
	linux/initramfs-tools/scripts/local-bottom/
		mount
			Mount things
		rsync
			Install things via rsync
		grub
			Install grub

If you find you'll need a binary program available in the initrd
that you don't have, then add a "copy_exec" line in one of the
files in here:		linux/initramfs-tools/hooks/

See also
--------

Man pages:
	initrd(4)
	mkinitramfs(8)
	initramfs-tools(8)
	rsyncd.conf(5)

Files:
	/usr/share/doc/syslinux/pxelinux.txt.gz

URLs:
	https://sources.bit.nl/viewvc.cgi/bit-pxe/
	https://weblog.bit.nl/blog/2008/03/11/bit-pxe-implementatie/
	http://tldp.org/HOWTO/Bootdisk-HOWTO/index.html
	http://wiki.voyage.hk/dokuwiki/doku.php?id=pxe_voyage

Note on partition scheme
------------------------

The default partition scheme is to support failsafe reflash in the field.

Only grub and config info should be kept in the first partition,
like NVRAM in other embedded devices.

The second partition (root1) should be the normal boot partition.

The third partition should be loaded at the factory with an image
of last resort. Perhaps something that DHCP's on eth0, then fetches
the correct image for root1 via HTTP, fixes the Grub install to a known
state and reboots. Also, it might need to have a NVRAM clear feature.

To boot root2, you have to have serial cable capability (in order to catch
grub and edit the boot params). To make this possible without serial
cable, you'd need to hack grub to teach it how to read the ALIX GPIO
lines to sense the reset button's state.

License
-------

The original bit-pxe was released to the public domain (more precisely,
as beerware).

These modifications are covered by a BSD-style license:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
     * 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.
     * The names of its contributors may not be used to endorse or
       promote products derived from this software without
       specific prior written permission.

THIS SOFTWARE IS PROVIDED BY Jeff R. Allen ''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 Jeff R. Allen 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.