Metadata-Version: 2.1
Name: virt-up
Version: 1.2.0
Summary: Create virtual machines quickly with virt-builder
Home-page: https://github.com/meffie/virt-up
Author: Michael Meffie
Author-email: mmeffie@sinenomine.net
License: BSD
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Dist: libvirt-python
Requires-Dist: sh

virt-up
=======

**virt-up** is a command line tool for creating virtual machines
quickly on a local KVM hypervisor using **virt-builder**, **virt-sysprep**,
and **virt-install**.

Virtual machines are created from existing digitally signed OS images, which
are downloaded and cached. A template virtual machine is created from the
downloaded image. Virtual machines are cloned from the template machine to
create new virtual machines quickly.

A login user and the ssh keys to connect to the new virtual machines are
created automatically. The login user is given sudo access. Connection
information is stored in a json meta data file for each virtual machine
created.

Normally you should run **virt-up** as a regular user, not root.

By default, **virt-up** will create image files in the ``default`` libvirt
storage pool (``/var/lib/libvirt/images``). See the ``pool`` option Settings to
change this.  Be sure you have read and write access to the configured libvirt
storage pool.

System requirements
===================

* Python 3.6 or better
* Local KVM hypervisor
* Python libvirt package
* ``qemu-img``, ``virt-builder``, ``virt-sysprep``, ``virt-install``

Usage
=====

::

    usage: virt-up [--name] <name> [--template <template>] [options]
                   --list [--all] | --list-templates
                   --login [--name] <name> [--command "<command>"]
                   --delete [--name] <name> | --delete --all

    positional arguments:
      <name>                instance name

    optional arguments:
      -h, --help            show this help message and exit
      --version             show program's version number and exit
      --list                list instances
      --list-templates      list template names
      --delete              delete the instance
      -t <template>, --template <template>
                            template name (default: <name>)
      --root-password <root-password>
                            root password (default: random)
      --user <user>         username (default: virt)
      --password <password>
                            password (default: random)
      --size <size>         instance disk size (default: image size)
      --memory <memory>     instance memory (default: 512)
      --vcpus <vcpus>       instance vcpus (default: 1)
      --graphics <graphics>
                            instance graphics type (default: none)
      --command <command>   --login ssh command
      --no-clone            build template instance only
      --all                 include template instances
      --yes                 answer yes to interactive questions
      --quiet               show less output
      --debug               show debug tracing


Settings
========

**virt-up** reads settings for INI formatted configuration files.
The following files are read in order, if they exist.

* ``/etc/virt-up/settings.cfg``
* ``$XDG_CONFIG_HOME/virt-up/settings.cfg`` (``$XDG_CONFIG_HOME`` is ``$HOME/.config`` if not set)

The ``settings.cfg`` should contain one section called ``[site]``. The following fields are supported:

pool
  The libvirt storage pool to write images. (default: ``default``)

username
  The username of the user account created by **virt-up** when creating
  new template instances (default: ``virt``)

dns-domain
  The DNS domain used for new template instance hostnames. (default: None)

address-source
  The method used to detect the instance IP address. Supported values are
  ``agent``, ``lease``, ``arp``, ``dns``. (default: ``agent``)

image-format
  The image format. Supported values are ``qcow2``, and ``raw``. (default: ``qcow2``)

virt-builder-args
  Extra arguments for ``virt-builder``. (default: None)

virt-sysprep-args
  Extra arguments for ``virt-sysprep``. (default: None)

virt-install-args
  Extra arguments for ``virt-install``. (default: None)


Template Defintions
===================

Additional OS types can be created with **virt-up** by providing template defintions
in the following files:

* ``/etc/virt-up/templates.cfg``
* ``$XDG_CONFIG_HOME/virt-up/templates.cfg`` (``$XDG_CONFIG_HOME`` is ``$HOME/.config`` if not set)

The ``templates.cfg`` files are INI formatted text files. Provide one section
for each template definition. The section name is the template name used in
virt-up ``--template`` option. The following fields are supported:

desc
  A text description, show by ``--list-templates``.

os-version
  The **virt-builder** ``<os_version>`` name. See ``virt-builder =-list`` for available names.

os-type
  The **virt-install** ``--os-type``

os-variant
  The **virt-install** ``--os-variant``. See ``osquery-info os`` for available names.

arch
  The target architecture.

virt-builder-args
  Template specific extra arguments for ``virt-builder``. (default: None)

virt-sysprep-args
  Template specific extra arguments for ``virt-sysprep``. (default: None)

virt-install-args =
  Template specific extra arguments for ``virt-install``. (default: None)


