--- a/README	Mon Jan 30 13:53:34 2012 +0200
+++ b/README	Mon Jan 30 14:57:25 2012 +0200
@@ -1,8 +1,115 @@
-Debian installer preseed-based bootstrapping.
+PKVLM - Debian installer preseed-based bootstrapping.
+
+Performs unattended bare-metal installs of machines to a working state (i.e. such that Puppet can continue).
 
 Generates customized debian-installer ISO images which contain host-specific debconf preseed data, config files and scripts.
 
-Also integrates with lvm/virt-install to create/install new libvirt-based machines based on the customized media.
+Uses a customized isolinux.cfg to load the machine-specific preseed.cfg from /cdrom via kernel command line options, 
+
+Also integrates with LVM/virt-install to create/install new libvirt-based machines on the local KVM host based on the customized media.
 
 Supports bootstrapping puppet (package + config (server, ssl certs)).
 
+## Files
+
+The debian installer source image (i.e. what you download from debian.org) goes into:
+    
+    iso/debian-X.Y.Z-ARCH-netinst.iso
+
+    XXX: hardcoded as `$INSTALLER_NAME` in pvklm-create
+
+The installer image is unpacked to:
+
+    images/debian-X.Y.Z-ARCH
+
+From where it is copied to:
+
+    image/debian-X.Y.Z-ARCH_HOSTNAME
+
+Then the preseed data is processed/copied/templated/etc from:
+
+    preseed/... -> image/debian-X.Y.Z-ARCH_HOSTNAME/...
+
+    (varies based on chosen options. This also configures scripts to be executed/files to be copied after install)
+
+And finally, the resulting customized host-specific ISO image is created at:
+
+    iso/debian-X.Y.Z-ARCH_HOSTNAME.iso
+
+## Operation
+
+Booting from the .iso loads the syslinux bootloader (isolinux/isolinux.bin, isolinux/boot.cat), which then looks for
+
+    isolinux/isolinux.cfg
+
+Our isolinux.cfg (generated from preseed/isolinux.cfg) loads the kernel/initrd from /install[.amd], and supplies the
+relevant kernel command-line arguments, which are processed by debian-installer:
+
+    auto=true priority=critical preseed/file=${PRESEED_MOUNT}/${PRESEED_NAME} preseed/file/checksum=${PRESEED_CHECKSUM} --                      ${INSTALL_BOOT_CONSOLE} quiet
+
+This loads our preseed.cfg (generated from preseed/preseed.cfg). The preseed.cfg then contains answers to all the d-i interactive
+questions. The preseed.cfg takes care of automating the installer itself.
+
+The preseed.cfg contains many templated variables, which are subsituted for variables defined in pvklm-create at ISO-creation time.
+
+The preseed.cfg also loads additional preseed files (generated from preseed/*.cfg), e.g.:
+
+    passwords.cfg       - crypted passwords; not under version control
+    host.cfg            - configure additional software installed on the host (exim)
+
+The preseed.cfg can also specify additional packages to install:
+
+    $PRESEED_PACKAGES
+
+    (defined within pkvlm-create)
+
+After the main installation process is complete, the installer can also execute arbitrary script commands from our preseed.cfg
+We use this to copy over configuration files from "$IMAGE/preseed-files" inside the ISO (generated from various files
+in preseed/files and preseed/.../files (e.g. puppet)) to the target system. These are used for more advanced customizations than the debconf
+preseeding lets us do:
+
+    - configure serial console (/etc/default/grub, update-grub, modify /etc/inittab)
+    - configure puppet (/etc/puppet/puppet.cfg, pre-install ssl certs to /etc/puppet/ssl)
+
+Once the installer is complete, it will reboot, and the newly installed/bootstrapped Debian Linux system will start up for the first time.
+
+If puppet was bootstrapped, the puppet agent will start its first run immediately (in the background via /etc/init.d/puppet, as normal).
+
+## Usage
+
+Some things are hardcoded in preseed/*
+Some things are hardcoded in pklvm-create (the shell script)
+Some things can be specified via `foo=...` options on the command line:
+
+    ./pkvlm-create [options] <name> [name=[value] [...]]
+    ./pkvlm-create asdf domain=test.pvl puppet_master=puppet-testing.paivola.fi
+
+These options are defind in pkvlm-create. Not all variables in preseed/... are configureable via options.
+
+The only required argument is the machine's name. It is given as the first non-option argument. 
+
+## Puppet
+
+Supports configuring the host as a puppet agent. Pass a puppet=yes opt:
+
+    ./pkvlm-create asdf puppet=yes
+
+The puppet server can be configured via `puppet_master=...`. It defaults to 'puppet' (i.e. match puppet's default behaviour to resolve a host called
+'puppet').
+
+### SSL
+
+Supports pre-installing Puppet's SSL certificates from:
+
+    preseed/puppet/ssl
+
+If the puppetmaster's CA cert is present in preseed/puppet/ssl/certs/ca.pem, it is included in the preseed-files. 
+
+You can also pre-generate a cert+pkey pair for the machine on the puppetmaster:
+
+    puppet cert --generate ...
+    scp $ssldir/{certs,private_keys}/...pem ...
+
+These will be copied from "preseed/puppet/ssl/{certs,private_keys}/${FQDN}.pem" to the preseed-files, and the agent
+will use them to connect to the puppetmaster.
+

--- a/README.debian-installer	Mon Jan 30 13:53:34 2012 +0200
+++ b/README.debian-installer	Mon Jan 30 14:57:25 2012 +0200
@@ -1,5 +1,7 @@
 # vim: set ft=conf
 
+General notes on using debian-installer preseeding, and the preseed.cfg that we use.
+
 # Debian Installer
 General guide: http://www.debian.org/releases/squeeze/amd64/index.html.en
 HOWTO: http://www.debian.org/releases/squeeze/amd64/apa.html.en

--- a/pkvlm-create	Mon Jan 30 13:53:34 2012 +0200
+++ b/pkvlm-create	Mon Jan 30 14:57:25 2012 +0200
@@ -16,7 +16,7 @@
 ## Command-line options
 function _help () {
     cat <<END
-Usage: $1 [options] <name> [param=value [...]]
+Usage: $1 [options] <name> [param=[value] [...]]
 
 Options:
     -h      Show this help text