README file for the Xenoboot CD ------------------------------- The Xenoboot CD is designed to allow centralized control of server booting over the internet. IP address allocation, etc. is done by a local dhcpd, then higher level control comes from the central boot servers over the WAN. Specifically, the CD boots to linux, then requests a script from the bootserver (using a CGI script over HTTP/S), and runs it. The CD contains a copy of the Erik Arjan Hendriks's "Two kernel Monte" module, which allows it to boot another linux kernel from the running system, and a modified version of Eric Biederman's "kexec" tools which can boot a linux bzImage, an ELF kernel image, or a multiboot kernel image. Because the CD boots to a full linux environment, the boot scripts supplied by the server can checksum and reinstall other parts of the filesystem, kernels, etc. before continuing the boot process. This allows remote recovery even if the local filesystem is trashed. The idea is that the Xenoboot CD is left in the drive and becomes a part of the normal boot sequence of the remotely administered machine. Obviously, for complete remote recovery, some sort of watchdog or remote reset switch is needed to fix wedged machines. 1) Building. The xenoboot CD is not shipped as an ISO image, as it needs to be tailored to specify your bootserver, and various other boot-time options. There is no "quick start" for this CD -- read all of this README and then play about with it. Then again, if you need to use xenoboot rather than, say, GRUB (http://www.gnu.org/software/grub/) or PXELINUX (http://syslinux.zytor.com/pxe.php), you're doing something fairly complicated already. The client/ directory contains a copy of the CD's contents and a script (factory.sh) which does the tailoring and packaging. You will need: - About 1.8 GB of free space (the final ISO image is about 425 MB) - A recent copy of mkisofs (from the cdrtools package, available at ftp://ftp.berlios.de/pub/cdrecord/cdrtools-2.0.tar.gz) - The ZISOFS tools (from http://freshmeat.net/projects/zisofs-tools) You can then burn the CD with any CD burning software that will take an ISO CD image file (e.g cdrecord, also in the cdrtools package). 2) Configuration Basic client configuration can be done by factory.sh, which sets up the following files: - The ID string of the CD is in a file /usr/bootme/ID - The file bootme/cacert.pem contains a CA cert, so that curl can authenticate the server before accepting a script from it. - bootme/pubring.gpg is a GPG keyring which must contain the key for verifying the signatures on downloaded bootscripts. - Network configuration options (see below) are in bootme/NETWORK. - The name and fallback IP address of the server are in bootme/BOOTSERVER and bootme/BOOTSERVER_IP. The port number is in bootme/BOOTPORT. The default CD image HAS NO ROOT PASSWORD. You will not be able to log in at the console unless you set one. You can edit /etc/shadow by: gunzip xenoboot-cd/isolinux/initrd.gz mount -o loop xenboboot-cd/isolinux/initrd /mnt vi /mnt/etc/shadow umount /mnt gzip xenoboot-cd/isolinux/initrd or by supplying one on a floppy disk (see section 3). The version number of the CD is kept in the file isolinux/isolinux.cfg, where it is passed to the kernel on boot, in the 'xenoboot=' command-line option. The server needs to serve files from a CGI script at https:///cgi-bin/bootme . A sample script and apache config fragment are supplied in the server/ directory. The files served should be GPG-signed with a key that is in the keyring on the CD, and ascii-armoured. The CA certificate which signed the server's cert must be copied onto the CD, as above. 3) Boot sequence. The Xenoboot CD boots to a ramdisk (isolinux/initrd.gz), scans the PCI bus and loads whatever drivers look plausible. At this stage it mounts /proc, /dev, /tmp, and the main CD filesystem on /usr, then passes control to /usr/bootme/bootscript. /usr/bootme/bootscript first mounts the first floppy disk (if it's there) on /mnt. If this succeeds, it copies the contents of the disk over the root filesystem, as a way to patch files in /etc, for example, without changing the initrd. Also, any configuration files that bootscript reads from /usr/bootme can be overridden by a file with the same name in /mnt (since /usr/ is read-only). Next it tries to bring up an ethernet interface, configures it, and puts some basic iptables packet filters in place. The /usr/bootme/NETWORK (or /mnt/NETWORK) file defines the following variables to control interface configuration: DHCP_INTERFACES: what i/fs to configure eith dhcpcd. STATIC_INTERFACES: what i/fs to configure with ifconfig. IFCONFIG_foo: arguments after 'ifconfig foo' GATEWAY: default route (or "") NAMESERVERS: dns servers, space separated (or "") HOSTNAME: hostname to use if DHCP isn't going to supply one If that succeeds, it finds all the IP addresses of the boot server from DNS, and for each address it uses 'curl' to make a HTTP request for the next-stage script. If it gets a script back, it first checks that the script is signed by a trusted GPG key, and then passes control to that script. The arguments of the HTTP request are: - The contents of the file /usr/bootme/ID (/mnt/ID) - The command line passed to the kernel at boot time - The contents of the file /ROOTID, or the root filesytem device - The system uptime in seconds - The details of the DHCP lease, from /etc/dhcpcd/dhcpcd-*.info If all the IP addresses fail, /usr/bootme/bootscript returns, and the RC scripts will keep running it again until it succeeds or a human intervenes. 4) Things to put in the bootscript: Start an SSHD: echo 'user:x:1000:100::/:/bin.sh' >> /etc/passwd echo 'user:(crypted password):1000:0:::::' >>/etc/shadow rm -f /etc/ssh/ssh_host* /usr/bin/ssh-keygen -t rsa1 -b 1024 -f /etc/ssh/ssh_host_key -N '' /usr/bin/ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N '' /usr/bin/ssh-keygen -d -f /etc/ssh/ssh_host_dsa_key -N '' (or copy in your own host keys) iptables -A INPUT -p tcp --dport 22 -j ACCEPT /usr/sbin/sshd sleep 600 Boot another linux kernel using the "two kernel monte" module (ported from linux 2.2 to 2.4 by tjd21): /usr/local/sbin/xenoboot-monte kernel foo bar (This is deprecated. Use kexec instead.) Boot another linux kernel using the "kexec" system call (ported from linux 2.5 to 2.4 by the nice folks at PlanetLab, and patched to load multiboot kernels by tjd21): /usr/local/sbin/xenoboot-kexec --command-line="foo bar" kernel (This script also tries to shut down a lot of drivers before rebooting.) Whatever else you feel like. Some trivial examples are given in the server/bootfiles directory. Don't forget to GPG-sign the boot files. A more complicated example: booting Xenoservers. The example file server/bootfiles/srgboot-xenoserver.sh does a bit of checking, sets up some useful functions and then loads a per-machine boot file. The per-machine boot file only needs to have a simple one-line command to specify what to boot. A sample per-machine file is in server/bootfiles/xenoboot.sh 5) Licenses, acknowledgements and such. Most of the software on the CD is taken from the gentoo linux distribution; license details are available in the source. Source code for the installed gentoo packages is included on the cd, in /usr/portage/distfiles. The Xenoboot scripts and utilities are copyright (C) 2002-2003 Tim Deegan , and distributed under the GNU General Public License; source code for binaries is in /usr/src on the CD. The Xenoboot utilities include modified versions of Eric Biederman's kexec code (with patches by the Planet-lab team), and of Erik Hendriks's two-kernel monte code. 6) Feedback If you have any comments or questions about Xenoboot, please email Tim Deegan . -- $Id: README,v 1.9 2004/02/20 12:21:27 tjd21 Exp $