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: Copyright (c) 2009, Jeff R. Allen All rights reserved. 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.