Provided by:
uvtool-libvirt_0~bzr92-0ubuntu1_all 
NAME
uvt-kvm - Ubuntu virtualisation front-end for libvirt and KVM
SYNOPSIS
uvt-kvm list
uvt-kvm create [options] name [filter ...]
uvt-kvm wait [options] name
uvt-kvm ip name
uvt-kvm ssh [options] [user@]name [command ...]
uvt-kvm destroy name
DESCRIPTION
uvtool provides a unified and integrated VM front-end to Ubuntu cloud
image downloads, libvirt, and cloud-init.
uvt-kvm uses the volume storage pool maintained by uvt-simplestreams-
libvirt(1) as a basis to provide quick start and management of Ubuntu
VMs by wrapping libvirt and cloud-init.
uvt-kvm is not intended to wrap all possible use cases. Where possible,
it provides access to some more advanced cases using options to
override entire sections of default operation, such as the ability to
directly override the backing volume image used, the libvirt domain
definition and cloud-init metadata and userdata. For yet more complex
cases, it is expected that the user will call libvirt directly (for
example by using virsh(1)), and use uvt-kvm for only the simpler
operations required on affected VMs. See ADVANCED OVERRIDE OPTIONS and
ADVANCED USAGE for details.
SUBCOMMANDS
uvt-kvm's interface is designed around subcommands. The subcommand to
be used must be specified as the first positional argument. Each
subcommand has its own set of available options.
Where a subcommand requires a VM to be specified, the VM name must be
provided as a second positional argument. When using uvt-kvm create to
create VMs, the VM name is specified by the user at this time. Where
users have manipulated libvirt directly, VM names are expected to match
libvirt domain names.
list
uvt-kvm list
Print a list of existing VMs to stdout. This list currently includes
libvirt domains that are defined but were not created by uvt-kvm, but
in future this is expected to change to VMs created by uvt-kvm only.
create
uvt-kvm create [options] name [filter ...]
Create a new VM based on a backing volume specified by the provided
simplestreams filters. This VM will be called name, and the same name
must be used when referring to the VM from the other subcommands.
Each filter operates on the images downloaded and managed by uvt-
simplestreams-libvirt(1), and when combined together must uniquely
specify a single image. See uvt-simplestreams-libvirt(1) for details on
image selection.
Since backing volume images are downloaded and maintained by uvt-
simplestreams-libvirt(1), it is necessary to first run uvt-
simplestreams-libvirt(1) to download images before this subcommand will
succeed. See EXAMPLES, below.
If no filters are specified, a filter of release=release is assumed,
where release corresponds to the current LTS release as returned by
distro-info(1).
This subcommand supports an extensive set of options to modify the
definition and behavior of the VM. See LIBVIRT DOMAIN DEFINTION
OPTIONS, CLOUD-INIT CONFIGURATION OPTIONS and ADVANCED OVERRIDE OPTIONS
below.
wait
uvt-kvm wait [options] name
Wait for a VM to become ready. This includes: waiting for the VM to
request an IP address, waiting for ssh to become available on this IP,
and an ssh(1) operation into the VM to wait for cloud-init to finish
and the system to enter runlevel 2.
By using the wait command, scripts can create, operate on and destroy
VMs synchronously and reliably.
--timeout timeout
Give up waiting after timeout seconds. Default: 120
seconds.
--interval interval
For wait operations that must poll, poll every interval
seconds. Default: 8 seconds.
--remote-wait-script remote_wait_script
Run remote_wait_script through sh(1) on the guest system,
which must block and exit with a zero status when the
system is ready. Default: /usr/share/uvtool/remote-
wait.sh, which assumes that upstart and cloud-init are
being used on the guest, waits for upstart to enter
runlevel 2 and then waits for cloud-init to signal that it
has finished booting the system.
When remote_wait_script is run on the guest system, its
environment will define the variables UVTOOL_WAIT_INTERVAL
and UVTOOL_WAIT_TIMEOUT which contain the poll interval
and wait timeout as specified by the --interval and
--timeout options, respectively.
--remote-wait-user user
Run the remote wait script as user user. It must be
possible to ssh(1) into the guest system as this user for
the remote wait mechanism to work.
--insecure Permit potentially insecure operations, which is currently
required for the remote wait script to work. See COMMON
OPTIONS, below.
--ssh-private-key-file ssh_private_key_file
Use ssh_private_key_file to authenticate to the guest
machine when performing the ssh(1) operation
--without-ssh
Skip the ssh(1) operation. This will cause the command to
exit with success as soon as the ssh port is available,
but without logging to the guest to wait until it is ready
internally.
ip
uvt-kvm ip name
Guess the IP address of a VM and print it to stdout. Currently, this
assumes a default (Ubuntu) installation of libvirt and dnsmasq on the
host, and default networking behaviour on the VM. IP address guessing
is currently implemented by examining dnsmasq's leases file
/var/lib/libvirt/dnsmasq/default.leases for the VM's NIC.
This subcommand assumes that the VM has successfully acquired an IP
address, and will fail otherwise. Callers can use uvt-kvm wait after
creating or rebooting a VM to wait for this to become the case.
In future, this subcommand may incorporate multiple IP address
detection mechanisms.
ssh
uvt-kvm ssh [options] [user@]name [command ...]
Run ssh(1) against the VM. This is a limited wrapper around ssh(1) and
the ip subcommand, designed for ease-of-use in the common case. For
full functionality, use the ip subcommand to obtain the VM's IP
address, and then call ssh(1) directly instead.
--insecure Permit potentially insecure operations, which is currently
required for this subcommand to work. See COMMON OPTIONS,
below.
--login-name user
-l user
Specify the username to pass to ssh(1). This is the
recommended method for use in scripts. This option
overrides the username provided by the @ notation in the
first positional argument, and thus allows the VM name to
include an @ symbol. Default: ubuntu, to match the default
on Ubuntu cloud images.
destroy
uvt-kvm destroy name
Stop and completely destroy an existing VM. This stops the libvirt
domain if it is running, undefines it, and deletes all volumes that had
been part of the domain's definition. It does not, however, delete any
backing volumes, thus keeping intact pristine Ubuntu cloud images as
maintained by uvt-simplestreams-libvirt(8).
COMMON OPTIONS
--insecure
Valid for: uvt-kvm wait, uvt-kvm ssh.
Permit connections which may not be secure. For ssh(1)
connections, this skips host key validation, since uvtool
currently has no mechanism to securely acquire the ssh host key
from a guest. In the common case, this should not be a problem
since the guest system is located on the same system and this
network path can be trusted. However, uvt-kvm will refuse to
make a connection (for uvt-kvm ssh) or skip steps (for uvt-
kvm wait) without this option, in order to make absolutely sure
that the user cannot compromise his path to the guest system
without being aware of this caveat.
-d
--developer
Valid for: uvt-kvm create only.
Turn on a set of options deemed most useful for developers but
not suitable for turning on by default. Currently this is the
same as specifying --unsafe-caching and --log-console-output but
this may change between releases.
Scripts should never use this option. To protect against future
changes to the definition of this option, they should instead
use the expansion defined above.
LIBVIRT DOMAIN DEFINITION OPTIONS
Valid for: uvt-kvm create only.
These options modify the definition of the guest VM, and its connection
to the host.
uvt-kvm create takes the default or user-supplied libvirt domain XML
template definition and modifies it according to the following
parameters. Each of these parameters has a sensible default which may
change between releases.
--memory size
Amount of system RAM in megabytes. Default: 512 (MiB).
--disk size
Size of the OS disk in gigabytes. Default: 8 (GiB).
--unsafe-caching
Do not flush guest syncs to the host on the OS disk. This can
improve guest I/O performance at the cost of losing data on host
power failure. This option is useful for ephemeral guest
machines that do not need to be persistent beyond a host power
cycle.
--cpu cores
Number of CPU cores. Default: 1.
--bridge bridge
Replace the first defined NIC with one that connects to the
given host bridge. Default: unaltered from the libvirt domain
template.
--log-console-output
Log output to a disk file on the host instead of to a pty. With
libvirt's default configuration on Ubuntu, this log can be found
in /var/log/libvirt/qemu/<name>.log. This options enables
retrospective examination of VM console output, but breaks
virsh console for interactive use.
CLOUD-INIT CONFIGURATION OPTIONS
Valid for: uvt-kvm create only.
These options modify operation within the guest VM itself.
Unless --user-data is used to override this behaviour, uvt-kvm
generates cloud-init userdata with some sensible defaults when a VM is
created. These defaults can be altered using the following options:
--password password
Permit login to the VM to the default user ubuntu and password
password. This is useful for debugging purposes, since it also
enables a VT login. Using this command line option leaks the
password used to other users on the same system, so should never
be used in production for security reasons.
Default: no password login.
--run-script-once script_file
Run script_file as root on the VM the first time it is booted,
but never again. This option can be used multiple times to run
multiple scripts. If the script exits with a non-zero status, it
will be left on the VM in /tmp for debugging purposes.
script_file will be copied to the guest, marked as executable,
and executed directly, so it must be an appropriate binary,
start with a shebang, or otherwise be directly executable by the
guest kernel.
Default: no scripts.
--ssh-public-key-file ssh_public_key_file
Permit login to the VM to the default user ubuntu and the ssh
keys specified in ssh_public_key_file.
Default: use the output of ssh-add -L if available; otherwise
use ~/.ssh/id_rsa.pub. If no source is found at all, then a
warning will be printed to stderr, and VM creation will continue
with no arrangement for access to the guest.
--packages package_list
Install the comma-separated packages specified in package_list
on first boot. This option can be used multiple times; each
additional option adds to the final package list.
Default: no packages.
ADVANCED OVERRIDE OPTIONS
Valid for: uvt-kvm create only.
--template template_file
The base libvirt domain definition XML template to use when
constructing a new VM's definition. This is dynamically altered
before domain creation; see LIBVIRT DOMAIN DEFINITION OPTIONS.
Default: /usr/share/uvtool/default.xml.
--user-data user_data_file
Override cloud-init userdata, instead using the file supplied.
This overrides all options in the section CLOUD-INIT
CONFIGURATION OPTIONS.
Default: as described in CLOUD-INIT CONFIGURATION OPTIONS.
--meta-data meta_data_file
Override default cloud-init metadata, instead using the file
supplied. This does not override any other options, since
cloud-init metadata is not otherwise tunable.
Default: minimal file with automatically generated instance-id.
ADVANCED USAGE
uvt-kvm is carefully constructed to avoid impeding the ability of the
user to directly use virsh(1) or other libvirt tooling at any time, and
provides override options to supply backing image volumes and cloud-
init userdata and metadata where possible. VMs created by uvt-kvm are
not "special" in libvirt. What uvt-kvm does with VMs is well-defined,
so that advanced users can manipulate a VM using libvirt directly
without necessarily losing the ability for uvt-kvm to continue to
manipulate that VM for common use cases.
TERMINOLOGY AND LIFECYCLE
For simplicity, uvt-kvm uses create to mean the definition, allocation
and running of a VM, and destroy to mean the stopping and removing of
all persistent state associated with a VM, including VM-specific disk
image files and the VM definition itself. This matches the commonly
expected lifecycle of VMs created with uvt-kvm.
This works well for the common use case, but if VMs created with uvt-
kvm need to be manipulated with virsh(1) or libvirt directly, then it
becomes necessary to understand how this matches up to the more complex
libvirt terminology.
In libvirt, a VM is called a domain. A domain is first defined, and
then independently started. In libvirt terminology, destroy means a VM
stop; after a destroy, the domain still exists and can be restarted.
undefine finally removes the domain definition. Resources associated
with a VM (such as disk image files, which in libvirt are called
volumes) must be created and destroyed separately.
When uvt-kvm creates a VM, libvirt volumes are defined and populated, a
libvirt domain is defined, marked as autostarted, and the domain
started. When uvt-kvm destroys a VM, the corresponding libvirt domain
is stopped, domain-specific volumes deleted and the libvirt domain
itself is undefined.
EXAMPLES
# Update uvtool's libvirt volume storage pool with the
# latest Precise image
uvt-simplestreams-libvirt sync release=precise arch=amd64
# Create an ssh key for the local user (if you don't have
# one already)
ssh-keygen
# (...)
# Create an amd64 VM running Precise
uvt-kvm create myvm release=precise arch=amd64
# Wait for the VM to become ready
uvt-kvm wait --insecure myvm
# Shell into the VM to do some testing there
uvt-kvm ssh --insecure myvm
# (...)
# Destroy the VM
uvt-kvm destroy myvm
TROUBLESHOOTING
Common Errors
Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied
Do you have permission to connect to libvirt? On Ubuntu, you must
belong to the libvirtd group. Users with sudo(8) access are added to
this group by default, but users only get group membership on the next
login after the libvirt-bin package has been installed. To temporarily
add yourself to this group in advance of your next login, try
newgrp libvirtd.
no supported architecture for os type 'hvm'
libvirt did not find KVM support on your system. Try sudo kvm-ok for
diagnostics, and service libvirt-bin restart to pick up any changes
before retrying.
Interactive console access
If you cannot access the VM from the host system, try using --password
to set a password for the default ubuntu user inside the VM, and then
logging in to the VM over the console in order to examine it from the
inside.
To access the console interactively, use virsh console name. However,
note that interactive access is disabled if you are using --log-
console-output or -d, so for interactive access you will have to drop
these options if you are using them.
If you are using --userdata, then --password will be overridden by it
and you will need to modify your cloud-init userdata manually to
achieve the same effect.
SEE ALSO
uvt-simplestreams-libvirt(1), distro-info(1), dnsmasq(8), virsh(1).