Provided by: uvtool-libvirt_0~bzr92-0ubuntu1.1_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).