+++ /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.