Import a sanitized version of Steel Toe, the provisioning system.

1 files changed, 166 insertions, 0 deletions

diff --git a/DESIGN b/DESIGN
new file mode 100644
index 0000000..24fe638
--- /dev/null
+++ b/DESIGN
@@ -0,0 +1,166 @@
+Design
+======
+
+Steel Toe is a system for automating kickstart installs.  It aims to be
+as hands off as possible.  
+
+
+The control chain
+-----------------
+
+There are several pieces that are required in order for a network
+kickstart install to work.  Here is a list of those pieces and what
+Steel Toe does and does not do for each piece.
+
+ DHCP Server
+	A DHCP server is required to answer the PXE request from the
+	client machine's BIOS/EFI.  The DHCP server will respond with an
+	address, network information, a filename, and the next server to
+	contact (usually the TFTP server).
+
+	Steel Toe does not manage the DHCP server's config file or
+	object database.  It can generate a section that can be
+	integrated into the ISC DHCPD's config file.  The idea here is
+	that the DHCP config information doesn't need to change unless
+	there is a major configuration change (MAC address change,
+	subnet migration, etc).  The network information should not
+	change, nor the filename of the bootloader (pxelinux.0 or
+	elilo.efi), nor the address of the TFTP server between installs.
+
+ TFTP server
+ 	A TFTP server is required to hand out the boot loaders and
+	config files to client machines.
+
+	Steel Toe does not provide a TFTP server, your OS should.
+
+ PXE/EFI boot loader
+ 	These files should be placed in your TFTP server directory.
+	Your dhcpd config file should point each client machine at the
+	correct file.
+
+	Steel Toe does not provide the boot loader files.
+
+ PXE/EFI config files
+ 	These files should be placed in your TFTP server directory.
+	There will be one file for each client machine.
+
+ 	Steel Toe will have to generate these files. 
+	Depending how much indirection we want to put on the file
+	system, these could be generated once.
+
+ Kernel and initrd images
+	These files are referenced in the PXE/EFI config files.
+ 	They need to be "in" the TFTP server directory so PXE/EFI can
+	fetch them.
+
+	Steel Toe will need to know where to find these files so it can
+	symlink them into the right host tree.
+
+ Kickstart file
+ 	These file are also referenced in the PXE/EFI config files.
+	They don't actually need to be on the file system.  They could
+	be generated on the fly by a CGI script.
+
+	Steel Toe will be responsible for generating kickstart files.
+
+ Install tree
+ 	These are the files that make up a full distribution install
+	tree.  It contains the kernel images, anaconda stage two images,
+	and all RPM packages for the distribution.
+
+	Steel Toe will be responsible for knowing where these bits are
+	and storing some classification information.  It will not be
+	responsible for putting the files where they need to be.  It
+	will provide a command to learn when new bits are available,
+	where the new bits are, and how they should be classified.
+
+DHCP config
+-----------
+
+filename option should look like "/tftpboot/hosts/$hostname/pxelinux.0"
+The rest is up to the admin.
+
+TFTP Structure
+--------------
+
+Steel Toe will generate and use the following type of directory
+structure inside the TFTP root.
+
+hosts/
+	$hostname/
+		pxelinux.0		# could be a link to another file
+		pxelinux.cfg -> .	# so the config file is here
+		default			# PXE config file
+		vmlinuz -> real-vmlinuz	# symlink to vmlinuz to boot with
+		initrd.img -> real-...	# symlink to initrd.img to boot with
+		ks.cfg			# kickstart file
+
+Here are the benefits for this method:
+
+ * We can always use the "default" config file.  We don't have to figure
+   out what the MAC address is, or convert the IP address to
+   hexadecimal.
+
+ * The PXE config file doesn't have to change.  They can point to
+   vmlinuz and initrd.img in the current directory.  We can just change
+   the symlinks to point to whatever we want to install.
+
+ * We can easily tell Apache to pull the tftpboot structure into the web
+   name space.  If we do that we don't have to keep track of another
+   directory to put generated files.
+
+Usage Cases
+===========
+
+Add new machine
+---------------
+
+ 1. Create XML document with new information
+ 2. Add document to database
+
+Add new install tree
+--------------------
+
+ 1. Specify path and classification information
+ 2. Create XML document
+ 3. Add document to database
+
+Install tree on machine
+-----------------------
+
+ 1. Specify machine and distro identifier
+ 2. Change vmlinuz and initrd.img symlinks to point to new distro
+ 3. Find kickstart block to use for machine
+ 4. Generate kickstart file
+ 5. Force machine to PXE boot
+
+Remove install tree
+-------------------
+
+Remove machine
+--------------
+
+Data Files
+==========
+
+There is only one data file that Steel Toe cares about,
+/etc/steeltoe/steeltoe.xml.  This file includes global config options,
+host config options, and install tree metadata.  If the file gets to
+large to manage you can take advantage of any tools available to you to
+make it more manageable.  You can use anything from XIncludes to
+generating the file with a shell script.  You just need to make sure the
+file is while when you run the Steel Toe commands.
+
+  Note: I ran some simple tests with a "large" config file that included
+        500 install trees and 200 clients.  Running xsltproc on such a
+        config file still took less than 30ms.
+
+
+Caveats
+=======
+
+The root disk is stored in the kickstart section, but Steel Toe only
+supports one name for the root disk.  If the device name changes, i.e.
+from hda to sda, between different install trees, Steel Toe will not
+handle it.
+