Add README

README

@@ -0,0 +1,115 @@
+.. vim: set ft=rst :
+
+====
+mkvm
+====
+
+``mkvm`` is a command-line tool and Python (3.x) API for creating Gentoo-based
+*libvirt*/KVM virtual machines.
+
+The ``mkvm`` command creates reproducible Gentoo system installations from
+declarative configuration descriptions. Its goal is to produce a minimum
+working environment that can then be managed by a configuration management
+package such as `Ansible`_.
+
+
+Features
+========
+
+* Reads virtual machine descriptions from YAML documents
+* Supports installing Gentoo onto LVM volumes and image files
+* Can fetch the latest stage3 tarball from a Gentoo mirror
+* Partitions virtual machine disks using GPT and/or LVM
+* Performs initial system configuration (e.g. filesystem mount configuration,
+  SSH host key generation, etc.)
+* Allows execution of custom scripts inside target system environments
+
+
+Requirements
+============
+
+* `Python`_ 3.3+
+* `setuptools`_
+* `libvirt-python`_
+* `pygpgme`_
+* `pyudev`_
+* `PyYAML`_
+
+
+Additionally, the following commands/packages may be needed:
+
+
+* ``losetup`` – Used to build raw file images
+* ``qemu-nbd`` – Used to build file images in *qcow2*, *vmdk*, etc.format
+* ``lvm2`` – Used to support logical volumes, either inside the target
+  system or on the host
+* ``sgdisk`` – Used to partition virtual disks with `GPT`_
+* ``wget`` – Used to fetch Gentoo stage3 tarballs
+
+
+Example
+=======
+
+Virtual machine description, in YAML format:
+
+.. code-block:: yaml
+
+    name: TestVM
+    fqdn: testvm.example.org
+    ram: 512M
+    vcpus: 2
+    net_ifaces:
+    - bridge: br0
+      mac: 52:54:00:40:5b:1c
+    image_format: qcow2
+    disk_size: 5G
+    disk_label: null
+    volumes:
+    - name: root
+      size: 3G
+      fstype: ext4
+      fsopts: ro,noatime,discard
+      mountpoint: /
+    - name: var
+      size: 1G
+      fstype: ext4
+      fsopts: noatime
+      mountpoint: /var
+    - name: var-log
+      size: 512M
+      fstype: ext4
+      fsopts: noatime
+      mountpoint: /var/log
+    kernel: /var/lib/libvirt/images/vmlinuz-3.18.12-gentoo.vm
+    initrd: /var/lib/libvirt/images/initramfs-genkernel-x86_64-3.18.12-gentoo.vm
+    kcmdline: >-
+      root=/dev/testvm/root ro dolvm rootfstype=ext4 nodetect fastboot quiet
+    boot:
+    - kernel
+    timezone: America/Chicago
+    customize: |
+      ln -s net.lo /etc/init.d/net.eth0
+      ln -s /etc/init.d/net.eth0 /etc/runlevels/default/
+      echo config_eth0="dhcp" > /etc/conf.d/net
+
+The following command will fetch the latest Gentoo stage3 tarball and create a
+machine using the above description:
+
+.. code-block:: sh
+
+    mkvm --latest testvm.yml
+
+
+.. note:: ``mkvm`` likely needs to be run as root in order to set up loopback
+   devices, create filesystems, etc. Future versions may use privilege
+   separation techniques to allow normal users to create virtual machines.
+
+
+.. _Ansible: http://www.ansible.com/
+.. _Python: http://www.python.org/
+.. _setuptools: https://pythonhosted.org/setuptools/
+.. _libvirt-python: http://www.libvirt.org/
+.. _pygpgme: https://pypi.python.org/pypi/pygpgme
+.. _pyudev: https://pypi.python.org/pypi/pyudev
+.. _PyYAML: http://pyyaml.org/
+.. _GPT: https://en.wikipedia.org/wiki/GUID_Partition_Table