--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+virt-tools - virtual machine information and statistics
+
+=head1 SYNOPSIS
+
+ virt-ifconfig
+
+ virt-uname
+
+ virt-ps
+
+=head1 DESCRIPTION
+
+Virt-tools are a set of tools that you can install in your virtual
+machines (guests) to get enhanced information about those guests.
+
+Unlike VMWare Tools, virt-tools is hypervisor agnostic. Also
+virt-tools does not include any performance enhancements for guests
+(see virtio if you want that).
+
+There are two parts to any virt-tools installation: some client
+programs like C<virt-uname> and C<virt-ps> that you run on the host,
+to query guest information. On the guest, you have to install and run
+a virt-tools service. Between the host and guest is a transport which
+should be secured. The L</HOST TOOLS> section describes the client
+programs available to run on the host. The L</GUEST CONFIGURATION>
+section describes how to configure guests and secure the transport.
+
+Finally the L</ARCHITECTURE> section describes the architecture of
+virt-tools and provides information about diagnosing problems.
+
+=head1 HOST TOOLS
+
+
+
+
+
+
+
+=head1 GUEST CONFIGURATION
+
+
+
+
+
+
+
+
+
+
+
+=head1 ARCHITECTURE
+
+Guests run an SNMP (Simple Network Management Protocol) server. The
+host client tools access this server in order to query information
+about the guest. They query this using standard SNMP calls.
+
+The protocol used is SNMPv3 (RFC 2571) which addresses security
+concerns in earlier versions of the protocol. In order to ensure that
+only the host can access the SNMP server, the guest generates a random
+secret key which the host must find out. Also the host must find a
+suitable transport to connect to the SNMP server (eg. by finding the
+IP address of the guest or using another transport into the guest).
+
+Once the secret key and the address of the guest are worked out, the
+query is a straightforward SNMP call:
+
+ +-----------------+ +-----------------+
+ | host | | guest |
+ | virt-x ---- request ---> snmpd |
+ | <---- reply ----- |
+ +-----------------+ +-----------------+
+
+The difficulty is in determining the secret key and the transport to
+use, which is what this section covers. You can also use this
+knowledge to diagnose problems, and to create non-standard
+configurations.
+
+=head2 DETERMINE SECRET KEY
+
+All the host tools use an external helper program called
+C<virt-tools-get-key> to get the secret key of the guest. (See
+L<virt-tools-get-key(8)> for the precise usage of this program).
+
+The secret key is generated by the guest once -- when the virt-tools
+package is installed in the guest. The secret key is written to a
+file C</etc/virt-tools/key> (in the guest) which is readable only by
+root.
+
+On Windows guests the secret key is written to
+C<%systemroot%\virttools.key>
+
+Using L<libguestfs(3)> the host can read any file in the guest, so it
+can read this secret key out directly. This is what the
+C<virt-tools-get-key> program does:
+
+ # virt-tools-get-key <name>
+ abcdef1234567890
+
+=head3 SECRET KEY CACHE
+
+C<virt-tools-get-key> caches the secret keys of guests that it has
+seen before so it doesn't have to read them each time. The cache is
+in C</var/lib/virt-tools/keys/>.
+
+You can just delete the files in this directory at any time, I<or> you
+can drop a file in here which contains the secret key of a guest.
+
+To do this, create a file C</var/lib/virt-tools/keys/E<lt>UUIDE<gt>>
+where E<lt>UUIDE<gt> is the guest's UUID as displayed by this command:
+
+ virsh domuuid <name>
+
+The contents of the file should be the secret key.
+
+You can test this works by running C<virt-tools-get-key> by hand.
+
+=head2 DETERMINE TRANSPORT
+
+All the host tools use a second helper program called
+C<virt-tools-get-transport> to get the transport and address to use
+for a guest. (See L<virt-tools-get-transport(8)> for the precise
+usage of this program).
+
+This program tries a series of methods to determine how to access a
+guest, be it through a direct network connection or over some
+hypervisor-specific channel.
+
+ # virt-tools-get-transport <name>
+ udp:192.168.122.33
+
+You can diagnose problems with the transport by trying to run this
+command by hand.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 Red Hat Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
git.annexia.org / virt-tools.git / blobdiff