Provided by: uvtool-libvirt_0~git140-0ubuntu1_all bug


       uvt-kvm - Ubuntu virtualisation front-end for libvirt and KVM


       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


       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


       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

       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.

       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.

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

       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

       --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/, 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

                    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.

       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.

       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.

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


              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.

              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.


       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.

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

              Instead of the default cpu model - which mostly is a compatibility  focused  lowest
              denominator  of  cpu  features - use host-passthrough which will try to make all of
              the hosts cpu features available in the guest.


       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

              Default:   use   the   output   of   ssh-add -L   if   available;   otherwise   use
              ~/.ssh/  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

              Default: no packages.


       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

              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  hosts  architecture  will  be  used  to
              determine the default xml template.

              Default: The architecture of the host system.

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

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


       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.

       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.


       # 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)
       # (...)

       # 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


   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.


       uvt-simplestreams-libvirt(1), distro-info(1), dnsmasq(8), virsh(1).