.. 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