From aa37cb49b40b16c31b8da25d5dbf251ef2b3209c Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Thu, 24 Sep 2009 12:55:37 +0100 Subject: [PATCH] More documentation. --- Makefile.am | 2 +- configure.ac | 2 +- docs/Makefile.am | 30 ---- docs/virt-tools.pod | 158 ------------------ tools/Makefile.am | 11 +- tools/virt-ifconfig.pl | 1 + tools/virt-uname.pl | 423 +++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 436 insertions(+), 191 deletions(-) delete mode 100644 docs/Makefile.am delete mode 100644 docs/virt-tools.pod diff --git a/Makefile.am b/Makefile.am index 400c0f5..4b5ade5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -17,4 +17,4 @@ EXTRA_DIST = virt-tools.spec -SUBDIRS = daemon docs linux tools +SUBDIRS = daemon linux tools diff --git a/configure.ac b/configure.ac index bdb3403..f2e9e8f 100644 --- a/configure.ac +++ b/configure.ac @@ -75,5 +75,5 @@ AC_CONFIG_FILES([tools/virt-ifconfig:tools/virt-ifconfig.pl], AC_CONFIG_FILES([Makefile virt-tools.spec - daemon/Makefile docs/Makefile linux/Makefile tools/Makefile]) + daemon/Makefile linux/Makefile tools/Makefile]) AC_OUTPUT diff --git a/docs/Makefile.am b/docs/Makefile.am deleted file mode 100644 index 6b22777..0000000 --- a/docs/Makefile.am +++ /dev/null @@ -1,30 +0,0 @@ -# virt-tools -# 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. - -EXTRA_DIST = virt-tools.8 virt-tools.pod - -man_MANS = virt-tools.8 - -virt-tools.8: virt-tools.pod - rm -f $@-t - $(POD2MAN) \ - --section 8 \ - -c "Virtualization Support" \ - --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ - < $< > $@-t - mv $@-t $@ - diff --git a/docs/virt-tools.pod b/docs/virt-tools.pod deleted file mode 100644 index 5d751bb..0000000 --- a/docs/virt-tools.pod +++ /dev/null @@ -1,158 +0,0 @@ -=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 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 the client -programs available to run on the host. 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 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 to get the secret key of the guest. (See -L 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 (in the guest) which is readable only by -root. - -On Windows guests the secret key is written to -C<%systemroot%\virttools.key> - -Using L the host can read any file in the guest, so it -can read this secret key out directly. This is what the -C program does: - - # virt-tools-get-key - abcdef1234567890 - -=head3 SECRET KEY CACHE - -C 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. - -You can just delete the files in this directory at any time, I you -can drop a file in here which contains the secret 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 secret key. - -You can test this works by running C by hand. - -=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 channel. - - # virt-tools-get-transport - 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) - -=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. diff --git a/tools/Makefile.am b/tools/Makefile.am index 7391185..dd7fdbe 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -30,6 +30,7 @@ bin_SCRIPTS = \ # These programs are hard linked to virt-uname. The Perl script uses # the value of argv[0] to work out which tool to run. PROGS = \ + virt-ping \ virt-ps install-exec-hook: @@ -37,7 +38,7 @@ install-exec-hook: ln $(DESTDIR)$(bindir)/virt-uname $(DESTDIR)$(bindir)/$$prog; \ done -man_MANS = $(generated_mans) virt-ifconfig.8 +man_MANS = $(generated_mans) virt-tools.8 virt-ifconfig.8 generated_mans = virt-uname.8 $(PROGS:%=%.8) @@ -46,6 +47,14 @@ $(generated_mans): echo '.so man8/virt-tools.8' > $@-t mv $@-t $@ +virt-tools.8: virt-uname + $(POD2MAN) \ + --section 8 \ + -c "Virtualization Support" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + --name "virt-tools" \ + $< > $@-t && mv $@-t $@ + virt-ifconfig.8: virt-ifconfig $(POD2MAN) \ --section 8 \ diff --git a/tools/virt-ifconfig.pl b/tools/virt-ifconfig.pl index 4197153..523c125 100755 --- a/tools/virt-ifconfig.pl +++ b/tools/virt-ifconfig.pl @@ -248,6 +248,7 @@ Most spreadsheets and databases can import CSV directly. =head1 SEE ALSO +L, L, L, L, 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. -- 1.8.3.1