X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=tools%2Fvirt-uname.pl;h=9bca435bb3b37e5f41dcab07d59121e3a2afbe7a;hb=aa37cb49b40b16c31b8da25d5dbf251ef2b3209c;hp=0b478b8dc1efb6fd48108339e991a7d8eddf5e86;hpb=854f4c38777ebb2527757d1a585774b0c856efa3;p=virt-tools.git diff --git a/tools/virt-uname.pl b/tools/virt-uname.pl index 0b478b8..9bca435 100755 --- a/tools/virt-uname.pl +++ b/tools/virt-uname.pl @@ -16,5 +16,428 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +use strict; + use Net::SNMP; +use Pod::Usage; +use Getopt::Long; +use Locale::TextDomain 'virt-tools'; + +=encoding utf8 + +=head1 NAME + +virt-uname, virt-ps, virt-ping - virtual machine information and statistics + +=head1 SYNOPSIS + + virt-uname [--options] [domname] + + virt-ps [--options] [domname] + + virt-ping [--options] [domname] + + virt-ifconfig [--options] [domname] + +=head1 COMMON OPTIONS + +All the tools take either a single C parameter, which is the +name of the virtual machine as known to libvirt (C), or no +parameter in which case they operate on all currently running guests. + +I You must install the C package in each +Linux guest, otherwise these programs will not work. + +There are some common options which can be supplied to any tool: + +=over 4 + +=cut + +my $help; + +=item B<--help> + +Display brief help. + +=cut + +my $version; + +=item B<--version> + +Display version number and exit. + +=cut + +my $uri; + +=item B<--connect URI> | B<-c URI> + +If using libvirt, connect to the given I. If omitted, then we +connect to the default libvirt hypervisor. + +=cut + +my $csv; + +=item B<--csv> + +Write out the results in CSV format (comma-separated values). This +format can be imported easily into databases and spreadsheets, but +read L below. + +=back + +=cut + +GetOptions ("help|?" => \$help, + "version" => \$version, + "connect|c=s" => \$uri, + "csv" => \$csv, + ) or pod2usage (2); +pod2usage (1) if $help; +if ($version) { + print "@PACKAGE_STRING@\n"; + exit +} + +my %subcommands = ( + "virt-uname" => [ &do_uname, &title_uname ], + "virt-ps" => [ &do_ps, &title_ps ], + "virt-ping" => [ &do_ping, &title_ping ], +); + +# Which subcommand? +my ($do_it, $title_it); +foreach (keys %subcommands) { + if ($0 =~ /$_/) { + $do_it = $subcommands{$_}->[0]; + $title_it = $subcommands{$_}->[1]; + last; + } +} +die "$0: cannot determine which sub-command to run\n" unless $do_it; + +# Do we have named guests? +if (@ARGV == 0) { + my $conn; + + if ($uri) { + $conn = Sys::Virt->new (readonly => 1, address => $uri); + } else { + $conn = Sys::Virt->new (readonly => 1); + } + + # Ignore inactive domains. + my @doms = $conn->list_domains (); + + my @domnames = map { $_->get_name () } @doms; + + if (@domnames) { + title_it (); + foreach (@domnames) { + my ($key, $transport); + eval { + $key = get_key ($_); + $transport = get_transport ($_); + }; + if (!$@) { do_it ($_, $key, $transport) } + } + } +} else { + title_it (); + foreach (@ARGV) { + my ($key, $transport); + eval { + $key = get_key ($_); + $transport = get_transport ($_); + }; + if (!$@) { do_it ($_, $key, $transport) } + } +} + +exit 0; + +=head1 virt-uname + +C displays the system information (kernel version etc) of +the guest. + +=cut + +sub title_uname +{ + print_row (__"Guest"); +} + +sub do_uname +{ + my $domname = shift; + my $key = shift; + my $transport = shift; + + + +} + +=head1 virt-ps + +C displays the process list of the guest. + +=cut + +sub title_ps +{ + print_row (__"Guest"); +} + +sub do_ps +{ + my $domname = shift; + my $key = shift; + my $transport = shift; + + + +} + +=head1 virt-ping + +C pings the guest by making an empty virt-tools request, +and checking that it replies. This can be used as a simple test that +virt-tools is available and working inside the guest. + +=cut + +sub title_ping +{ + print_row (__"Guest"); +} + +sub do_ping +{ + my $domname = shift; + my $key = shift; + my $transport = shift; + + + +} + +# virt-ifconfig is implemented separately. + +=head1 virt-ifconfig + +C displays the IP address of the guest. + +=cut + +=head1 OVERVIEW + +Virt-tools are a set of tools that you can install in your virtual +machines (host and guests) to get enhanced information about the +guests. + +Unlike VMWare Tools, virt-tools is hypervisor agnostic. Also +virt-tools is just about collecting statistics and does not include +any performance or functionality enhancements for guests (see virtio +if you want that). + +There are two parts to any virt-tools installation: some client +programs like C and C 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 section describes how +to configure guests and secure the transport. + +Finally the L section describes the architecture of +virt-tools and provides information about diagnosing problems. + +=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 key and the transport to the guest are worked out, the query +is a straightforward SNMP call: + + +-----------------+ +-----------------+ + | host | | guest | + | virt-ps --- request ---> snmpd | + | <---- reply ----- | + +-----------------+ +-----------------+ + +The difficulty is in determining the 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 KEY + +All the host tools use an external helper program called +C to get the key of the guest. (See +L for the precise usage of this program). + +The key is generated by the guest once -- when the virt-tools package +is installed in the guest. The key is written to a file +C (in the guest) which is readable only by +root. + +On Windows guests the key is written to +C<%systemroot%\virttools.key> + +Using L the host can read any file in the guest, so it +can read this key out directly. This is what the +C program does, and you can run it by hand to +verify its operation: + + # virt-tools-get-key -v domname|uuid + abcdef1234567890 + +=head3 KEY CACHE + +C caches the keys of guests that it has seen +before so it doesn't have to read them each time. The cache is in +C (in the host). + +You can just delete the files in this directory at any time, I you +can drop a file in here which contains the key of a guest. + +To do this, create a file CUUIDE> +where EUUIDE is the guest's UUID as displayed by this command: + + virsh domuuid + +The contents of the file should be the key. + +You can test this works by running C by hand. + +This cache never expires, unless you remove the files by hand. + +=cut + +sub get_key +{ +} + +=head2 DETERMINE TRANSPORT + +All the host tools use a second helper program called +C to get the transport and address to use +for a guest. (See L 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 vmchannel. + + # virt-tools-get-transport -v domname|uuid + udp:192.168.122.33 + +You can diagnose problems with the transport by trying to run this +command by hand. + +=head3 TRANSPORT CACHE + +C caches the transports of guests that it +has seen before so it doesn't have to determine them each time. The +cache is in C (in the host). + +As for the L, this directory is just some files that are +named after the UUID of the guest, containing the transport. + +Unlike the key cache, C will check that a +transport is still valid, and will expire (ie. delete) the +corresponding entry in the transport cache if it is not valid. + +=cut + +sub get_transport +{ +} + +=head1 NOTE ABOUT CSV FORMAT + +Comma-separated values (CSV) is a deceptive format. It I like +it should be easy to parse, but it is definitely not easy to parse. + +Myth: Just split fields at commas. Reality: This does I work +reliably. This example has two columns: + + "foo,bar",baz + +Myth: Read the file one line at a time. Reality: This does I +work reliably. This example has one row: + + "foo + bar",baz + +For shell scripts, use C (L +also packaged in major Linux distributions). + +For other languages, use a CSV processing library (eg. C +for Perl or Python's built-in csv library). + +Most spreadsheets and databases can import CSV directly. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +=over 4 + +=item * + +Richard W.M. Jones (C) + +=item * + +Matthew Booth (C) + +=back + +=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.