tools/virt-uname.pl

   1 #!/usr/bin/perl -w
   2 # virt-tools
   3 # Copyright (C) 2009 Red Hat Inc.
   4 #
   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.
   9 #
  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.
  14 #
  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.
  18
  19 use strict;
  20
  21 use Net::SNMP;
  22 use Pod::Usage;
  23 use Getopt::Long;
  24 use Locale::TextDomain 'virt-tools';
  25
  26 =encoding utf8
  27
  28 =head1 NAME
  29
  30 virt-uname, virt-ps, virt-ping - virtual machine information and statistics
  31
  32 =head1 SYNOPSIS
  33
  34  virt-uname [--options] [domname]
  35
  36  virt-ps [--options] [domname]
  37
  38  virt-ping [--options] [domname]
  39
  40  virt-ifconfig [--options] [domname]
  41
  42 =head1 COMMON OPTIONS
  43
  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.
  47
  48 I<Note:> You must install the C<virt-tools-guest> package in each
  49 Linux guest, otherwise these programs will not work.
  50
  51 There are some common options which can be supplied to any tool:
  52
  53 =over 4
  54
  55 =cut
  56
  57 my $help;
  58
  59 =item B<--help>
  60
  61 Display brief help.
  62
  63 =cut
  64
  65 my $version;
  66
  67 =item B<--version>
  68
  69 Display version number and exit.
  70
  71 =cut
  72
  73 my $uri;
  74
  75 =item B<--connect URI> | B<-c URI>
  76
  77 If using libvirt, connect to the given I<URI>.  If omitted, then we
  78 connect to the default libvirt hypervisor.
  79
  80 =cut
  81
  82 my $csv;
  83
  84 =item B<--csv>
  85
  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.
  89
  90 =back
  91
  92 =cut
  93
  94 GetOptions ("help|?" => \$help,
  95             "version" => \$version,
  96             "connect|c=s" => \$uri,
  97             "csv" => \$csv,
  98     ) or pod2usage (2);
  99 pod2usage (1) if $help;
 100 if ($version) {
 101     print "@PACKAGE_STRING@\n";
 102     exit
 103 }
 104
 105 my %subcommands = (
 106     "virt-uname" => [ &do_uname, &title_uname ],
 107     "virt-ps" => [ &do_ps, &title_ps ],
 108     "virt-ping" => [ &do_ping, &title_ping ],
 109 );
 110
 111 # Which subcommand?
 112 my ($do_it, $title_it);
 113 foreach (keys %subcommands) {
 114     if ($0 =~ /$_/) {
 115         $do_it = $subcommands{$_}->[0];
 116         $title_it = $subcommands{$_}->[1];
 117         last;
 118     }
 119 }
 120 die "$0: cannot determine which sub-command to run\n" unless $do_it;
 121
 122 # Do we have named guests?
 123 if (@ARGV == 0) {
 124     my $conn;
 125
 126     if ($uri) {
 127         $conn = Sys::Virt->new (readonly => 1, address => $uri);
 128     } else {
 129         $conn = Sys::Virt->new (readonly => 1);
 130     }
 131
 132     # Ignore inactive domains.
 133     my @doms = $conn->list_domains ();
 134
 135     my @domnames = map { $_->get_name () } @doms;
 136
 137     if (@domnames) {
 138         title_it ();
 139         foreach (@domnames) {
 140             my ($key, $transport);
 141             eval {
 142                 $key = get_key ($_);
 143                 $transport = get_transport ($_);
 144             };
 145             if (!$@) { do_it ($_, $key, $transport) }
 146         }
 147     }
 148 } else {
 149     title_it ();
 150     foreach (@ARGV) {
 151         my ($key, $transport);
 152         eval {
 153             $key = get_key ($_);
 154             $transport = get_transport ($_);
 155         };
 156         if (!$@) { do_it ($_, $key, $transport) }
 157     }
 158 }
 159
 160 exit 0;
 161
 162 =head1 virt-uname
 163
 164 C<virt-uname> displays the system information (kernel version etc) of
 165 the guest.
 166
 167 =cut
 168
 169 sub title_uname
 170 {
 171     print_row (__"Guest");
 172 }
 173
 174 sub do_uname
 175 {
 176     my $domname = shift;
 177     my $key = shift;
 178     my $transport = shift;
 179
 180
 181
 182 }
 183
 184 =head1 virt-ps
 185
 186 C<virt-ps> displays the process list of the guest.
 187
 188 =cut
 189
 190 sub title_ps
 191 {
 192     print_row (__"Guest");
 193 }
 194
 195 sub do_ps
 196 {
 197     my $domname = shift;
 198     my $key = shift;
 199     my $transport = shift;
 200
 201
 202
 203 }
 204
 205 =head1 virt-ping
 206
 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.
 210
 211 =cut
 212
 213 sub title_ping
 214 {
 215     print_row (__"Guest");
 216 }
 217
 218 sub do_ping
 219 {
 220     my $domname = shift;
 221     my $key = shift;
 222     my $transport = shift;
 223
 224
 225
 226 }
 227
 228 # virt-ifconfig is implemented separately.
 229
 230 =head1 virt-ifconfig
 231
 232 C<virt-ifconfig> displays the IP address of the guest.
 233
 234 =cut
 235
 236 =head1 OVERVIEW
 237
 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
 240 guests.
 241
 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
 245 if you want that).
 246
 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.
 253
 254 Finally the L</ARCHITECTURE> section describes the architecture of
 255 virt-tools and provides information about diagnosing problems.
 256
 257 =head1 GUEST CONFIGURATION
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269 =head1 ARCHITECTURE
 270
 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.
 274
 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).
 281
 282 Once the key and the transport to the guest are worked out, the query
 283 is a straightforward SNMP call:
 284
 285  +-----------------+      +-----------------+
 286  | host            |      | guest           |
 287  |  virt-ps --- request ---> snmpd          |
 288  |         <---- reply -----                |
 289  +-----------------+      +-----------------+
 290
 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.
 294
 295 =head2 DETERMINE KEY
 296
 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).
 300
 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
 304 root.
 305
 306 On Windows guests the key is written to
 307 C<%systemroot%\virttools.key>
 308
 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:
 313
 314  # virt-tools-get-key -v domname|uuid
 315  abcdef1234567890
 316
 317 =head3 KEY CACHE
 318
 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).
 322
 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.
 325
 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:
 328
 329  virsh domuuid <name>
 330
 331 The contents of the file should be the key.
 332
 333 You can test this works by running C<virt-tools-get-key> by hand.
 334
 335 This cache never expires, unless you remove the files by hand.
 336
 337 =cut
 338
 339 sub get_key
 340 {
 341 }
 342
 343 =head2 DETERMINE TRANSPORT
 344
 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).
 349
 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.
 353
 354  # virt-tools-get-transport -v domname|uuid
 355  udp:192.168.122.33
 356
 357 You can diagnose problems with the transport by trying to run this
 358 command by hand.
 359
 360 =head3 TRANSPORT CACHE
 361
 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).
 365
 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.
 368
 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.
 372
 373 =cut
 374
 375 sub get_transport
 376 {
 377 }
 378
 379 =head1 NOTE ABOUT CSV FORMAT
 380
 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.
 383
 384 Myth: Just split fields at commas.  Reality: This does I<not> work
 385 reliably.  This example has two columns:
 386
 387  "foo,bar",baz
 388
 389 Myth: Read the file one line at a time.  Reality: This does I<not>
 390 work reliably.  This example has one row:
 391
 392  "foo
 393  bar",baz
 394
 395 For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
 396 also packaged in major Linux distributions).
 397
 398 For other languages, use a CSV processing library (eg. C<Text::CSV>
 399 for Perl or Python's built-in csv library).
 400
 401 Most spreadsheets and databases can import CSV directly.
 402
 403 =head1 SEE ALSO
 404
 405 L<virt-ifconfig(8)>,
 406 L<guestfs(3)>,
 407 L<guestfish(1)>,
 408 L<Sys::Guestfs(3)>,
 409 L<Sys::Guestfs::Lib(3)>,
 410 L<Sys::Virt(3)>,
 411 L<http://libguestfs.org/>.
 412
 413 =head1 AUTHORS
 414
 415 =over 4
 416
 417 =item *
 418
 419 Richard W.M. Jones (C<rjones at redhat dot com>)
 420
 421 =item *
 422
 423 Matthew Booth (C<mbooth at redhat dot com>)
 424
 425 =back
 426
 427 =head1 COPYRIGHT
 428
 429 Copyright (C) 2009 Red Hat Inc.
 430
 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.
 435
 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.
 440
 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.