trusty (1) uvt-kvm.1.gz

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