docs/virt-tools.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 virt-tools - virtual machine information and statistics
   6
   7 =head1 SYNOPSIS
   8
   9  virt-ifconfig
  10
  11  virt-uname
  12
  13  virt-ps
  14
  15 =head1 DESCRIPTION
  16
  17 Virt-tools are a set of tools that you can install in your virtual
  18 machines (guests) to get enhanced information about those guests.
  19
  20 Unlike VMWare Tools, virt-tools is hypervisor agnostic.  Also
  21 virt-tools does not include any performance enhancements for guests
  22 (see virtio if you want that).
  23
  24 There are two parts to any virt-tools installation: some client
  25 programs like C<virt-uname> and C<virt-ps> that you run on the host,
  26 to query guest information.  On the guest, you have to install and run
  27 a virt-tools service.  Between the host and guest is a transport which
  28 should be secured.  The L</HOST TOOLS> section describes the client
  29 programs available to run on the host.  The L</GUEST CONFIGURATION>
  30 section describes how to configure guests and secure the transport.
  31
  32 Finally the L</ARCHITECTURE> section describes the architecture of
  33 virt-tools and provides information about diagnosing problems.
  34
  35 =head1 HOST TOOLS
  36
  37
  38
  39
  40
  41
  42
  43 =head1 GUEST CONFIGURATION
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55 =head1 ARCHITECTURE
  56
  57 Guests run an SNMP (Simple Network Management Protocol) server.  The
  58 host client tools access this server in order to query information
  59 about the guest.  They query this using standard SNMP calls.
  60
  61 The protocol used is SNMPv3 (RFC 2571) which addresses security
  62 concerns in earlier versions of the protocol.  In order to ensure that
  63 only the host can access the SNMP server, the guest generates a random
  64 secret key which the host must find out.  Also the host must find a
  65 suitable transport to connect to the SNMP server (eg. by finding the
  66 IP address of the guest or using another transport into the guest).
  67
  68 Once the secret key and the address of the guest are worked out, the
  69 query is a straightforward SNMP call:
  70
  71  +-----------------+      +-----------------+
  72  | host            |      | guest           |
  73  |  virt-x ---- request ---> snmpd          |
  74  |         <---- reply -----                |
  75  +-----------------+      +-----------------+
  76
  77 The difficulty is in determining the secret key and the transport to
  78 use, which is what this section covers.  You can also use this
  79 knowledge to diagnose problems, and to create non-standard
  80 configurations.
  81
  82 =head2 DETERMINE SECRET KEY
  83
  84 All the host tools use an external helper program called
  85 C<virt-tools-get-key> to get the secret key of the guest.  (See
  86 L<virt-tools-get-key(8)> for the precise usage of this program).
  87
  88 The secret key is generated by the guest once -- when the virt-tools
  89 package is installed in the guest.  The secret key is written to a
  90 file C</etc/virt-tools/key> (in the guest) which is readable only by
  91 root.
  92
  93 On Windows guests the secret key is written to
  94 C<%systemroot%\virttools.key>
  95
  96 Using L<libguestfs(3)> the host can read any file in the guest, so it
  97 can read this secret key out directly.  This is what the
  98 C<virt-tools-get-key> program does:
  99
 100  # virt-tools-get-key <name>
 101  abcdef1234567890
 102
 103 =head3 SECRET KEY CACHE
 104
 105 C<virt-tools-get-key> caches the secret keys of guests that it has
 106 seen before so it doesn't have to read them each time.  The cache is
 107 in C</var/lib/virt-tools/keys/>.
 108
 109 You can just delete the files in this directory at any time, I<or> you
 110 can drop a file in here which contains the secret key of a guest.
 111
 112 To do this, create a file C</var/lib/virt-tools/keys/E<lt>UUIDE<gt>>
 113 where E<lt>UUIDE<gt> is the guest's UUID as displayed by this command:
 114
 115  virsh domuuid <name>
 116
 117 The contents of the file should be the secret key.
 118
 119 You can test this works by running C<virt-tools-get-key> by hand.
 120
 121 =head2 DETERMINE TRANSPORT
 122
 123 All the host tools use a second helper program called
 124 C<virt-tools-get-transport> to get the transport and address to use
 125 for a guest.  (See L<virt-tools-get-transport(8)> for the precise
 126 usage of this program).
 127
 128 This program tries a series of methods to determine how to access a
 129 guest, be it through a direct network connection or over some
 130 hypervisor-specific channel.
 131
 132  # virt-tools-get-transport <name>
 133  udp:192.168.122.33
 134
 135 You can diagnose problems with the transport by trying to run this
 136 command by hand.
 137
 138 =head1 AUTHORS
 139
 140 Richard W.M. Jones (C<rjones at redhat dot com>)
 141
 142 =head1 COPYRIGHT
 143
 144 Copyright (C) 2009 Red Hat Inc.
 145
 146 This program is free software; you can redistribute it and/or modify
 147 it under the terms of the GNU General Public License as published by
 148 the Free Software Foundation; either version 2 of the License, or
 149 (at your option) any later version.
 150
 151 This program is distributed in the hope that it will be useful,
 152 but WITHOUT ANY WARRANTY; without even the implied warranty of
 153 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 154 GNU General Public License for more details.
 155
 156 You should have received a copy of the GNU General Public License
 157 along with this program; if not, write to the Free Software
 158 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.