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.
24 use Locale::TextDomain 'virt-tools';
30 virt-uname, virt-ps, virt-ping - virtual machine information and statistics
34 virt-uname [--options] [domname]
36 virt-ps [--options] [domname]
38 virt-ping [--options] [domname]
40 virt-ifconfig [--options] [domname]
44 All the tools take either a single C<domname> parameter, which is the
45 name of the virtual machine as known to libvirt (C<virsh list>), or no
46 parameter in which case they operate on all currently running guests.
48 I<Note:> You must install the C<virt-tools-guest> package in each
49 Linux guest, otherwise these programs will not work.
51 There are some common options which can be supplied to any tool:
69 Display version number and exit.
75 =item B<--connect URI> | B<-c URI>
77 If using libvirt, connect to the given I<URI>. If omitted, then we
78 connect to the default libvirt hypervisor.
86 Write out the results in CSV format (comma-separated values). This
87 format can be imported easily into databases and spreadsheets, but
88 read L</NOTE ABOUT CSV FORMAT> below.
94 GetOptions ("help|?" => \$help,
95 "version" => \$version,
96 "connect|c=s" => \$uri,
99 pod2usage (1) if $help;
101 print "@PACKAGE_STRING@\n";
106 "virt-uname" => [ &do_uname, &title_uname ],
107 "virt-ps" => [ &do_ps, &title_ps ],
108 "virt-ping" => [ &do_ping, &title_ping ],
112 my ($do_it, $title_it);
113 foreach (keys %subcommands) {
115 $do_it = $subcommands{$_}->[0];
116 $title_it = $subcommands{$_}->[1];
120 die "$0: cannot determine which sub-command to run\n" unless $do_it;
122 # Do we have named guests?
127 $conn = Sys::Virt->new (readonly => 1, address => $uri);
129 $conn = Sys::Virt->new (readonly => 1);
132 # Ignore inactive domains.
133 my @doms = $conn->list_domains ();
135 my @domnames = map { $_->get_name () } @doms;
139 foreach (@domnames) {
140 my ($key, $transport);
143 $transport = get_transport ($_);
145 if (!$@) { do_it ($_, $key, $transport) }
151 my ($key, $transport);
154 $transport = get_transport ($_);
156 if (!$@) { do_it ($_, $key, $transport) }
164 C<virt-uname> displays the system information (kernel version etc) of
171 print_row (__"Guest");
178 my $transport = shift;
186 C<virt-ps> displays the process list of the guest.
192 print_row (__"Guest");
199 my $transport = shift;
207 C<virt-ping> pings the guest by making an empty virt-tools request,
208 and checking that it replies. This can be used as a simple test that
209 virt-tools is available and working inside the guest.
215 print_row (__"Guest");
222 my $transport = shift;
228 # virt-ifconfig is implemented separately.
232 C<virt-ifconfig> displays the IP address of the guest.
238 Virt-tools are a set of tools that you can install in your virtual
239 machines (host and guests) to get enhanced information about the
242 Unlike VMWare Tools, virt-tools is hypervisor agnostic. Also
243 virt-tools is just about collecting statistics and does not include
244 any performance or functionality enhancements for guests (see virtio
247 There are two parts to any virt-tools installation: some client
248 programs like C<virt-uname> and C<virt-ps> that you run on the host,
249 to query guest information. On the guest, you have to install and run
250 a virt-tools service. Between the host and guest is a transport which
251 should be secured. The L</GUEST CONFIGURATION> section describes how
252 to configure guests and secure the transport.
254 Finally the L</ARCHITECTURE> section describes the architecture of
255 virt-tools and provides information about diagnosing problems.
257 =head1 GUEST CONFIGURATION
271 Guests run an SNMP (Simple Network Management Protocol) server. The
272 host client tools access this server in order to query information
273 about the guest. They query this using standard SNMP calls.
275 The protocol used is SNMPv3 (RFC 2571) which addresses security
276 concerns in earlier versions of the protocol. In order to ensure that
277 only the host can access the SNMP server, the guest generates a random
278 secret key which the host must find out. Also the host must find a
279 suitable transport to connect to the SNMP server (eg. by finding the
280 IP address of the guest or using another transport into the guest).
282 Once the key and the transport to the guest are worked out, the query
283 is a straightforward SNMP call:
285 +-----------------+ +-----------------+
287 | virt-ps --- request ---> snmpd |
288 | <---- reply ----- |
289 +-----------------+ +-----------------+
291 The difficulty is in determining the key and the transport to use,
292 which is what this section covers. You can also use this knowledge to
293 diagnose problems, and to create non-standard configurations.
297 All the host tools use an external helper program called
298 C<virt-tools-get-key> to get the key of the guest. (See
299 L<virt-tools-get-key(8)> for the precise usage of this program).
301 The key is generated by the guest once -- when the virt-tools package
302 is installed in the guest. The key is written to a file
303 C</var/lib/virt-tools/key> (in the guest) which is readable only by
306 On Windows guests the key is written to
307 C<%systemroot%\virttools.key>
309 Using L<libguestfs(3)> the host can read any file in the guest, so it
310 can read this key out directly. This is what the
311 C<virt-tools-get-key> program does, and you can run it by hand to
312 verify its operation:
314 # virt-tools-get-key -v domname|uuid
319 C<virt-tools-get-key> caches the keys of guests that it has seen
320 before so it doesn't have to read them each time. The cache is in
321 C</var/lib/virt-tools/keys/> (in the host).
323 You can just delete the files in this directory at any time, I<or> you
324 can drop a file in here which contains the key of a guest.
326 To do this, create a file C</var/lib/virt-tools/keys/E<lt>UUIDE<gt>>
327 where E<lt>UUIDE<gt> is the guest's UUID as displayed by this command:
331 The contents of the file should be the key.
333 You can test this works by running C<virt-tools-get-key> by hand.
335 This cache never expires, unless you remove the files by hand.
343 =head2 DETERMINE TRANSPORT
345 All the host tools use a second helper program called
346 C<virt-tools-get-transport> to get the transport and address to use
347 for a guest. (See L<virt-tools-get-transport(8)> for the precise
348 usage of this program).
350 This program tries a series of methods to determine how to access a
351 guest, be it through a direct network connection or over some
352 hypervisor-specific vmchannel.
354 # virt-tools-get-transport -v domname|uuid
357 You can diagnose problems with the transport by trying to run this
360 =head3 TRANSPORT CACHE
362 C<virt-tools-get-transport> caches the transports of guests that it
363 has seen before so it doesn't have to determine them each time. The
364 cache is in C</var/lib/virt-tools/transports/> (in the host).
366 As for the L</KEY CACHE>, this directory is just some files that are
367 named after the UUID of the guest, containing the transport.
369 Unlike the key cache, C<virt-tools-get-transport> will check that a
370 transport is still valid, and will expire (ie. delete) the
371 corresponding entry in the transport cache if it is not valid.
379 =head1 NOTE ABOUT CSV FORMAT
381 Comma-separated values (CSV) is a deceptive format. It I<seems> like
382 it should be easy to parse, but it is definitely not easy to parse.
384 Myth: Just split fields at commas. Reality: This does I<not> work
385 reliably. This example has two columns:
389 Myth: Read the file one line at a time. Reality: This does I<not>
390 work reliably. This example has one row:
395 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
396 also packaged in major Linux distributions).
398 For other languages, use a CSV processing library (eg. C<Text::CSV>
399 for Perl or Python's built-in csv library).
401 Most spreadsheets and databases can import CSV directly.
409 L<Sys::Guestfs::Lib(3)>,
411 L<http://libguestfs.org/>.
419 Richard W.M. Jones (C<rjones at redhat dot com>)
423 Matthew Booth (C<mbooth at redhat dot com>)
429 Copyright (C) 2009 Red Hat Inc.
431 This program is free software; you can redistribute it and/or modify
432 it under the terms of the GNU General Public License as published by
433 the Free Software Foundation; either version 2 of the License, or
434 (at your option) any later version.
436 This program is distributed in the hope that it will be useful,
437 but WITHOUT ANY WARRANTY; without even the implied warranty of
438 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
439 GNU General Public License for more details.
441 You should have received a copy of the GNU General Public License
442 along with this program; if not, write to the Free Software
443 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.