3 # Copyright (C) 2009 Red Hat Inc.
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or
8 # (at your option) any later version.
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, write to the Free Software
17 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25 use Locale::TextDomain 'virt-tools';
31 virt-uname, virt-ps, virt-ping - virtual machine information and statistics
35 virt-uname [--options] [domname]
37 virt-ps [--options] [domname]
39 virt-ping [--options] [domname]
41 virt-ifconfig [--options] [domname]
45 All the tools take either a single C<domname> parameter, which is the
46 name of the virtual machine as known to libvirt (C<virsh list>), or no
47 parameter in which case they operate on all currently running guests.
49 I<Note:> You must install the C<virt-tools-guest> package in each
50 Linux guest, otherwise these programs will not work.
52 There are some common options which can be supplied to any tool:
70 Display version number and exit.
76 =item B<--connect URI> | B<-c URI>
78 If using libvirt, connect to the given I<URI>. If omitted, then we
79 connect to the default libvirt hypervisor.
87 Write out the results in CSV format (comma-separated values). This
88 format can be imported easily into databases and spreadsheets, but
89 read L</NOTE ABOUT CSV FORMAT> below.
95 =item B<--verbose> | B<-v>
97 Enable verbose messages, useful for debugging.
103 GetOptions ("help|?" => \$help,
104 "version" => \$version,
105 "connect|c=s" => \$uri,
107 "verbose|v" => \$verbose,
109 pod2usage (1) if $help;
111 print "@PACKAGE_STRING@\n";
116 "virt-uname" => [ \&do_uname, \&title_uname ],
117 "virt-ps" => [ \&do_ps, \&title_ps ],
118 "virt-ping" => [ \&do_ping, \&title_ping ],
122 my ($do_it, $title_it);
123 foreach (keys %subcommands) {
125 print STDERR "subcommand = $_\n" if $verbose;
126 $do_it = $subcommands{$_}->[0];
127 $title_it = $subcommands{$_}->[1];
131 die "$0: cannot determine which sub-command to run\n" unless $do_it;
133 # If we are being run from a local directory, add that directory to
134 # the path, so we can be run from the source directory without being
136 if (substr ($0, 0, 1) ne "/") {
139 $ENV{PATH} = "$_:$ENV{PATH}"; # XXX Windows?
140 print STDERR "PATH set to $ENV{PATH}\n" if $verbose;
145 # Do we have named guests?
150 $conn = Sys::Virt->new (readonly => 1, address => $uri);
152 $conn = Sys::Virt->new (readonly => 1);
155 # Ignore inactive domains.
156 my @doms = $conn->list_domains ();
158 my @domnames = map { $_->get_name () } @doms;
162 foreach (@domnames) {
175 # Turn any errors into warnings.
177 my ($key, $transport);
179 $transport = get_transport ($_);
180 &$do_it ($_, $key, $transport);
188 print STDERR "errors = $errors\n" if $verbose;
190 exit ($errors == 0 ? 0 : 1);
194 C<virt-uname> displays the system information (kernel version etc) of
201 print_row (__"Guest", __"System name");
208 my $transport = shift;
210 my $session = get_snmp_session ($key, $transport);
211 my $sysDescr = "1.3.6.1.2.1.1.1.0";
212 my $r = $session->get_request (-varbindlist => [$sysDescr])
213 or die __x("SNMP error: {e}", $session->error);
214 print_row ($domname, $r->{$sysDescr});
220 C<virt-ps> displays the process list of the guest.
226 print_row (__"Guest");
233 my $transport = shift;
241 C<virt-ping> pings the guest by making an empty virt-tools request,
242 and checking that it replies. This can be used as a simple test that
243 virt-tools is available and working inside the guest.
249 print_row (__"Guest");
256 my $transport = shift;
262 # virt-ifconfig is implemented separately.
266 C<virt-ifconfig> displays the IP address of the guest.
284 # XXX Use Text::CSV here.
288 } elsif ($_ =~ /,/ || $_ =~ /\n/) {
300 Virt-tools are a set of tools that you can install in your virtual
301 machines (host and guests) to get enhanced information about the
304 Unlike VMWare Tools, virt-tools is hypervisor agnostic. Also
305 virt-tools is just about collecting statistics and does not include
306 any performance or functionality enhancements for guests (see virtio
309 There are two parts to any virt-tools installation: some client
310 programs like C<virt-uname> and C<virt-ps> that you run on the host,
311 to query guest information. On the guest, you have to install and run
312 a virt-tools service. Between the host and guest is a transport which
315 The L</GUEST ARCHITECTURE> section describes how virt-tools appears
318 The L</HOST ARCHITECTURE> section describes the architecture of
319 virt-tools on the host side.
321 =head1 GUEST ARCHITECTURE
323 In most cases, you can just install the C<virt-tools-guest> package in
324 your Linux guests, or the Windows virt-tools guest package in your
325 Windows guests, and everything should just work. In this section we
326 describe more about how it works (or is supposed to work) from the
329 =head2 COMMUNICATIONS DIRECTORY
331 The guest writes various static, mostly unchanging, information into
332 its own directory. On Linux the directory is
333 C<@localstatedir@/lib/virt-tools/> and under Windows it is
334 C<%systemroot%\virttool\>. In the discussion below, this
335 communications directory is referred to as C<$GUESTCOMMSDIR>.
337 The host is able to read files out of this directory using
338 L<libguestfs(3)> (without any cooperation needed by the guest).
342 The host can't easily see the guest's IP address. The host provides
343 the guest with a network interface connected to a bridge, but the
344 guest can use any IP address it likes (although well-behaved guests
345 will usually have some static IPs or are allocated one by DHCP).
347 So when the guest starts up, or its IP address changes (usually these
348 are rare events) the guest writes a file
349 C<$GUESTCOMMSDIR/ip-E<lt>ifaceE<gt>> which contains details of the IP
350 address of the interface E<lt>ifaceE<gt> (eg. the file might be called
351 C<ip-eth0> under Linux).
353 C<virt-ifconfig> reads this file directly using L<libguestfs(3)>.
357 When the guest is first installed (or more precisely, when the
358 virt-tools-guest package is first installed in the guest), a random
359 secret key is generated. This is used to encrypt communications with
360 the guest, and it is described in more detail below.
362 The key is written to C<$GUESTCOMMSDIR/key>.
366 For process listings, and just about every other piece of data except
367 for IP address, guests run a completely standard SNMP (Simple Network
368 Management Protocol) server. The host client tools access this server
369 in order to query information about the guest. They query this using
372 The protocol used is SNMPv3 (RFC 2571) which addresses security
373 concerns in earlier versions of the protocol. In order to ensure that
374 only the host can access the SNMP server and see the results, all
375 communications are encrypted and authenticated using the guest's key.
379 There is not necessarily a network connection between the host and the
380 guest. There are many configurations of virtualization in which the
381 host has no network access to the guest: for example, if the host
382 firewalls itself off from the guest (or vice versa), or if the guest
383 has a physically separate network card from the host.
385 Therefore the guest to host SNMP transport is not necessarily over an
386 IP network. Other transports are possible, including "vmchannel"
387 (where "vmchannel" is the generic name for a collection of specialized
388 host-guest communication channels implemented in different ways by
389 different hypervisors).
391 The transport is written to C<$GUESTCOMMSDIR/transport>.
393 =head1 HOST ARCHITECTURE
395 On the host side, the host uses L<libguestfs(3)> to read the guest's
396 IP address and key, and uses some heuristics to determine the
399 Once the key and the transport to the guest are worked out, programs
400 like C<virt-ps>, C<virt-uname> and so on are just making
401 straightforward SNMP calls:
403 +-----------------+ +-----------------+
405 | virt-ps --- request ---> snmpd |
406 | <---- reply ----- |
407 +-----------------+ +-----------------+
409 The difficulty is in determining the key and the transport to use,
410 which is what this section covers. You can also use this knowledge to
411 diagnose problems or to create non-standard configurations.
415 All the host tools use an external helper program called
416 C<virt-tools-get-key> to get the key of the guest. (See
417 L<virt-tools-get-key(8)> for the precise usage of this program).
419 The key is generated by the guest once -- when the virt-tools-guest
420 package is installed in the guest. The key is written to a file
421 C<$GUESTCOMMSDIR/key> (in the guest) which is readable only by root.
423 Using L<libguestfs(3)> the host can read any file in the guest, so it
424 can read this key out directly. This is what the
425 C<virt-tools-get-key> program does, and you can run it by hand to
426 verify its operation:
428 # virt-tools-get-key -v domname
433 C<virt-tools-get-key> caches the keys of guests that it has seen
434 before so it doesn't have to read them each time. The cache is in
435 C<@localstatedir@/lib/virt-tools/keys/> (in the host).
437 You can just delete the files in this directory at any time, I<or> you
438 can drop a file in here which contains the key of a guest.
440 To do this, create a file
441 C<@localstatedir@/lib/virt-tools/keys/E<lt>UUIDE<gt>> where
442 E<lt>UUIDE<gt> is the guest's UUID as displayed by this command:
446 The contents of the file should be the key.
448 You can test this works by running C<virt-tools-get-key> by hand.
450 This cache never expires, unless you remove the files by hand.
458 my $cmd = "virt-tools-get-key";
459 $cmd .= " -v" if $verbose;
461 $cmd .= " -c '$uri'" if $uri;
462 $cmd .= " '$domname'";
464 print STDERR "$cmd\n" if $verbose;
466 open PIPE, "$cmd |" or die "$cmd: $!";
468 die __"no response from virt-tools-get-key\n" unless $line;
475 =head2 DETERMINE TRANSPORT
477 All the host tools use a second helper program called
478 C<virt-tools-get-transport> to get the transport and address to use
479 for a guest. (See L<virt-tools-get-transport(8)> for the precise
480 usage of this program).
482 This program tries a series of methods to determine how to access a
483 guest, be it through a direct network connection or over some
484 hypervisor-specific vmchannel.
486 # virt-tools-get-transport -v domname
489 You can diagnose problems with the transport by trying to run this
492 =head3 TRANSPORT CACHE
494 C<virt-tools-get-transport> caches the transports of guests that it
495 has seen before so it doesn't have to determine them each time. The
496 cache is in C<@localstatedir@/lib/virt-tools/transports/> (in the
499 As for the L</KEY CACHE>, this directory is just some files that are
500 named after the UUID of the guest, containing the transport.
502 Unlike the key cache, C<virt-tools-get-transport> will check that a
503 transport is still valid, and will expire (ie. delete) the
504 corresponding entry in the transport cache if it is not valid.
512 my $cmd = "virt-tools-get-transport";
513 $cmd .= " -v" if $verbose;
515 $cmd .= " -c '$uri'" if $uri;
516 $cmd .= " '$domname'";
518 print STDERR "$cmd\n" if $verbose;
520 open PIPE, "$cmd |" or die "$cmd: $!";
522 die __"no response from virt-tools-get-transport\n" unless $line;
531 Standard SNMP queries are used between the host and guest.
533 SNMP already supports many of the features we are trying to query
534 (eg. the UCD SNMP MIB provides a way to query the process list of a
535 machine in a form which is a de facto standard).
537 To determine what precise queries are sent, run the tools in verbose
538 mode or examine the source.
545 my $transport = shift;
547 my ($hostname, $port, $domain);
548 if ($transport =~ /^udp:(.*):(.*)/) {
552 } elsif ($transport =~ /^tcp:(.*):(.*)/) {
557 die __x("unknown transport type: {t}", t => $transport);
561 print STDERR "creating Net::SNMP session to $domain:$hostname:$port with key $key\n"
564 my ($session, $error) = Net::SNMP->session (
566 -username => "virttools",
567 -authpassword => $key,
568 -authprotocol => "sha",
569 -privpassword => $key,
570 -privprotocol => "aes",
571 -hostname => $hostname,
575 die __x("SNMP failure: {e}", e => $error) unless $session;
580 =head2 RUNNING YOUR OWN SNMP SERVER IN A GUEST
584 =head1 NOTE ABOUT CSV FORMAT
586 Comma-separated values (CSV) is a deceptive format. It I<seems> like
587 it should be easy to parse, but it is definitely not easy to parse.
589 Myth: Just split fields at commas. Reality: This does I<not> work
590 reliably. This example has two columns:
594 Myth: Read the file one line at a time. Reality: This does I<not>
595 work reliably. This example has one row:
600 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
601 also packaged in major Linux distributions).
603 For other languages, use a CSV processing library (eg. C<Text::CSV>
604 for Perl or Python's built-in csv library).
606 Most spreadsheets and databases can import CSV directly.
614 L<Sys::Guestfs::Lib(3)>,
616 L<http://libguestfs.org/>.
624 Richard W.M. Jones (C<rjones at redhat dot com>)
628 Matthew Booth (C<mbooth at redhat dot com>)
634 Copyright (C) 2009 Red Hat Inc.
636 This program is free software; you can redistribute it and/or modify
637 it under the terms of the GNU General Public License as published by
638 the Free Software Foundation; either version 2 of the License, or
639 (at your option) any later version.
641 This program is distributed in the hope that it will be useful,
642 but WITHOUT ANY WARRANTY; without even the implied warranty of
643 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
644 GNU General Public License for more details.
646 You should have received a copy of the GNU General Public License
647 along with this program; if not, write to the Free Software
648 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.