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

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