README

USAGE

+Introduction
+============
 
+ debian-vm creates a small, low memory usage, user-defined Debian vm disk image
+ which can be used in various hypervisors including VMware and kvm
+
+Prerequisites
+=============
+
+ - >= bash-4.0
+ - chroot (Debian chroot package)
+ - debootstrap (Debian debootstrap package)
+ - qemu-img (Debian qemu package)
+ - qemu-nbd (Debian qemu-tools package)
+ - nbd kernel module (either as a module, or compiled in with max_part >= 4)
+ - mfks.* for the used file systems
+ - mkswap
+
+
+Usage
+=====
+ - modify the debian_vm_settings.sh to fit your needs
+ - add the desired operations to the USER-DEFINED PARTS 1-5
+ - execute debian_vm.sh
+
+
+How does it work?
+=================
+
+debian_vm_settings.sh
+---------------------
+ All global configuration options can be modified in this file. Every other
+ script uses the options in this file.
+ QEMU_IMG_* options set the size and type of the generated base disk image
+ PARTITION_* options set the size, type and mount point of the partitions in the image
+ DEBIAN_* options set the version, source and arch of the installed Debian
+ INTERFACES describe the interfaces to be used in the vm
+ USERNAME and PUBLIC_KEY_FILE describes a user with a Key-Based SSH login
+ NUM_HOST and HOSTNAME_BASENAME describe the number of images to be generated
+ and the base name for those images
+
+debian_vm_base.sh
+-----------------
+ This script uses debootstrap to create a base debian system, then generates
+ the necessary configuration files (/etc/network/interfaces, /etc/apt/sources.list,
+ /etc/fstab).
+ It then executes USER-DEFINED PART 1. In this part the desired modifications
+ can be made to the system before chrooting (e.g. copying source files to
+ be compiled).
+ The script chroots and executes a script in the chroot jail which sets up
+ apt, installs the necessary packages and creates the user.
+ It then executes USER-DEFINED PART 2. This part can be used to install
+ extra packages, and do whatever is required in the system.
+ The script then cleans the system and exits from the chroot.
+ It modifies the completed system and executes USER-DEFINED PART 3. In this
+ part the almost-ready system can be modified from the outside.
+ 
+debian_vm_fs.sh
+---------------
+ This script creates the image using qemu-img and connects it to an nbd 
+ with qemu-nbd (network block device, used to access a thin-provisioned
+ virtualization image as a block device in this case).
+ It creates the configured partitions, filesystems and swap spaces, then
+ mounts the filesystems.
+
+
+debian_vm_ondisk.sh
+-------------------
+ This script copies the contents of the system to the filesystems in the
+ vm image. It then the chroots into the system (now on the virtual image),
+ and installs grub2 on the system. It executes USER-DEFINED PART 4 at this
+ point.
+
+
+debian_vm_finalize.sh
+---------------------
+ This script unmounts the filesystems and disconnects the vm image from
+ the nbd device, then uses qemu-img to strip the image of unnecessary blocks,
+ reducing the size of the final base image.
+ It then sets the base image read-only.
+
+
+debian_vm_perhost.sh
+--------------------
+ This script creates a vm image for every host using the base image as a
+ backing image (Redirect-on-Write in qemu terminology).
+ It mounts every host image and chroots into it, then executes the necessary
+ host-based modifications (e.g. setting the hostname). It then executes
+ USER-DEFINED PART 5 where per-host modifications can be made.
+ The script then creates a volatile image using the host image as a backing
+ image.
+
+
+Result
+------
+ The result of the script is the generated base image, host images and
+ volatile host images in the build/ directory.
+ The images use the following backing chain:
+ hostN_volatile.img -> hostN.img -> base.img
+ These three images should be copied to the supervisor. After usage, the
+ hostN_volatile.img can be replaces with the original, effectively restoring
+ the original state of the host.