======
box.py
======

Box.py is a simple automation tool meant to run Ubuntu or Fedora cloud images
on top of VirtualBox.

What it does is simply download official cloud image, set up VM, tweak it up
and do the initial pre-configuration using generated config drive.

I've wrote this little tool just to not click myself to death using web browser
for downloading cloud images, and going through VirtualBox GUI (or figuring out
weird named options for ``vboxmanage`` ;P)


Requirements
------------

- Python 3.x

  - `pyyaml`_

- Virtualbox (obviously)
- ``mkisofs`` or ``genisoimage`` command for generating iso image
- ``wget`` command for fetching images
- ``sha256sum`` command for checksum check
- ``qemu-img`` from *qemu-utils* package command for converting between images
  formats


How to run it
-------------

First, make sure you fulfill the requirements; either by using packages from
your operating system, or by using virtualenv for Python requirements, i.e.:

.. code:: shell-session

   $ python -m virtualenv .venv
   $ . .venv/bin/activate
   (.venv) $ pip install requirements.txt

than you can issue:

.. code:: shell-session

   $ alias boxpy='python /path/to/box.py'

or simply link it somewhere in the path:

.. code:: shell-session

   $ ln -s /path/to/box.py ~/bin/boxpy
   $ chmod +x ~/bin/boxpy

and now you can issue some command. There are four command for simple managing
VMs, maybe some other will be available in the future. Who knows.

For your convenience there is a bash completion for each command, so you can
use it ad-hoc, or place on your ``.bashrc`` or whatever:

.. code:: shell-session

   $ source <(boxpy completion bash)

currently there are four commands available:

- ``list`` - for quickly listing all/running VMs
- ``destroy`` - that is probably obvious one
- ``create`` and ``rebuild``

The latter two accepts several options besides required vm name. You can
examine it by using ``--help``.

What is more interesting though, is the fact, that you can pass your own
`cloud-init`_ yaml file, so that VM can be provisioned in easy way.

Default user-script looks as follows:

.. code:: yaml

   users:
     - default
     - name: ubuntu
       ssh_authorized_keys:
         - $ssh_key
       chpasswd: { expire: False }
       gecos: ubuntu
       sudo: ALL=(ALL) NOPASSWD:ALL
       groups: users, admin
   power_state:
     mode: poweroff
     timeout: 10
     condition: True

It is really simple, and use ``string.Template`` for exchanging token
``$ssh_key`` with default, or provided public key, so that you will be able to
log in into the VM using that key. Section ``power_state`` is used internally
for making sure the cloud-init finish up and the VM will be started again.

Note, that you need to be extra careful regarding ``$`` sign. As explained
above ``$ssh_key`` will be used as a "variable" for the template to substitute
with the real value of public key. Every ``$`` sign, especially in
``write_files.contents``, should be escaped with another dollar, so the ``$``
will become a ``$$``. Perhaps I'll change the approach for writing ssh key,
since that's a little bit annoying.

For that reason, a little improvement has been done, so now its possible to
pass filenames to the custom config, instead of filling up
``write_files.contents``:

.. code:: yaml

   write_files:
     - path: /opt/somefile.txt
       permissions: '0644'
       filename: /path/to/local/file.txt

during processing this file, boxpy will look for ``filename`` key in the yaml
file for the ``write_files`` sections, and it will remove that key read the
file and put its contents under ``content`` key. What is more important, that
will be done after template processing, so that there will be no interference
for possible ``$`` characters.

What is more interesting is the fact, that you could use whatever cloud-init
accepts, and a special section, for keeping configuration, so that you don't
need to provide all the option every time you boot up similar VM. For example:

.. code:: yaml

   packages:
     - jq
     - silversearcher-ag
     - tmux
     - vim-nox
   runcmd:
     - [su, -, ubuntu, -c, "echo 'set nocompatible' > .vimrc"]
   boxpy_data:
     key: vm
     cpus: 4
     memory: 4GB
     disk_size: 20GB

Contents of the user script will be merged with the default one, so expect,
that user ``ubuntu`` will be there, and magically you'll be able to connect to
the machine using ssh.

Providing file with this content using ``--cloud-config``, will build a VM with
4 CPUs, 4GB of RAM, expand Ubuntu-server image to 20GB (it'll be dynamically
allocated VDI image, so it will not swallow all 20 gigs of space) and pass the
``vm`` ssh key, which will be looked in ``~/.ssh`` directory, if path to the
key is not provided.

Moreover, there will be some tools installed and simple vim config
initialized, just to make you an idea, what could be done with it.

You can find some real world examples of the yaml cloud-init files that I use
in examples directory.


License
-------

This work is licensed under GPL-3.


.. _pyyaml: https://github.com/yaml/pyyaml
.. _cloud-init: https://cloudinit.readthedocs.io