Provided by: uvtool-libvirt_0~git178-0ubuntu1.23.10.1_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, cloud-init metadata and userdata, and directly provide a
network-config file. 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).
Alternatively, see --backing-image-file under ADVANCED OVERRIDE OPTIONS below to supply a
backing image directly yourself.
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. Other general behavioural options:
--no-start Do not start the VM after creation. This is useful to make further
customisations to the VM before using it. To start the VM when done, use
virsh start name.
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. 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 via libvirt-python.
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. 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. This is no longer be required in the default case, since uvtool
creates the guest's host keys, supplies them to the guest via cloud-init, and thus
knows and sets the expected host public key automatically. In the common non-
default case, --insecure may be required but still 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).
--ephemeral-disk size
Add an ephemeral disk of Size gigabytes.
--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.
--mac mac
Use this MAC address for the first defined NIC. Can be used in conjunction with
--bridge. Default unspecified.
--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. On s390x this option is currently not supported
due to incompatibilties with the sclp console used.
--host-passthrough
Instead of the default CPU model - which is host-model this will use host-
passthrough which will try to make all of the host's CPU features (not migration
safe) available in the guest. This option is deprecated and will later be removed.
Please use --model instead.
--cpu-model
Set the CPU model that shall be used. The default generally is host-model, except
on arm64 where host-model won't work - there the default is host-passthrough. If
set to host-model or host-passthrough this will set the CPU mode. If set to any
other string it will be handled as a named CPU passed to libvirt. Allowed values
are all CPUs listed on your host as usable=yes in `virsh domcapabilities`. This
option has no effect if the target is emulated, in this case the safe defaults of
libvirt will be used.
--machine-type type
Set the machine type to the specified string before instantiating the guest. See
kvm -M ? for a list of types supported by your current system. If not set this
section of the template is not altered before the guest is defined. If set this
modifies the internal temporary libvirt domain template at the element
domain->os->type and sets the attribute machine to the given value before defining
the guest. This implies that libvirt will add the type-dependent default devices
when defining the guest.
If --machine-type is not specified, the current host is an x86_64 system and the
requested guest is arch=amd64 then the machine type will by default be set to the
latest available q35 based type to overcome the ancient compatibility oriented
defaults of libvirt on x86.
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/libvirt/template.xml.
--guest-arch architecture
Specify the architecture of the guest template file that will be selected. If an
explicit --template is given then --guest-arch has no effect. If neither
--template nor --guest-arch are set the host's architecture will be used to
determine the default xml template.
If you set an architecture that requires emulation on the current host the guest
will be set up for that. See EMULATION OF FOREIGN ARCHITECTURES for more details on
using an architecture that is different to the current system.
Default: Current Host architecture
--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.
--network-config network_config_file
Provide cloud-init network-config using the file supplied.
Default: no network-config file.
--backing-image-file image_file
Specify the name of a local file that will be used to create the VM instead of
relying on the volume storage pool. It must point to a qcow2 formatted file. This
option overrides any simplestreams filters provided.
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.
EMULATION OF FOREIGN ARCHITECTURES
emulation of foreign architectures can be done with uvt-kvm. Currently armhf being the
only supported target architecture. Please be aware that defining filters to use a
different architecture image will not be enough. To let uvtool know that you want to run
as a specific architecture you need to set --guest-arch If that is set to armhf (just like
your simplestreams filters for the image would be) then uvt-kvm will use qemu-system-arm
Since in these modes bootloaders often struggle uvt-kvm will provide externel kernel and
initrd to boot the guest. To be able to extract those from the guest image it needs root
permission when syncing the non native architecture image.
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 libvirt
group (this group was named libvirtd on 16.04 and earlier). 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 libvirt (or newgrp libvirtd if on Ubuntu
16.04 or earlier).
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 --user-data, 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).