--- /dev/null
+*~
+*.8
+Makefile
+Makefile.in
+aclocal.m4
+autom4te.cache
+config.log
+config.status
+configure
+install-sh
+missing
+tools/virt-ifconfig
+tools/virt-tools-get-key
+tools/virt-tools-get-transport
+tools/virt-uname
--- /dev/null
+virt-tools - virtual machine info and statistics
+Copyright (C) Red Hat Inc. 2009
+----------------------------------------------------------------------
+
+
+Requirements
+----------------------------------------------------------------------
+
+In the host:
+
+ Perl 5
+
+ Perl modules:
+
+ - Net::SNMP
+
+ - Sys::Virt (Perl bindings for libvirt)
+
+ - Sys::Guestfs (part of libguestfs) [optional]
+
+ pod2man (usually part of Perl)
+
+ libvirt
+
+ libguestfs
+
+ fping
+
+In the guest, for Unix/Linux guests:
+
+ net-snmp (a portable SNMP server, nothing to do with Perl Net::SNMP)
+
+
+Build and install
+----------------------------------------------------------------------
+
+To build and install on a Unix/Linux system you would do:
+
+ ./configure
+ make
+
+as root:
+
+ make install
+
+Note that this installs everything (client scripts which should be run
+on the host, and the service configuration which should be run in the
+guest).
--- /dev/null
+# 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.
+
+SUBDIRS = daemon docs linux tools
+virt-tools - virtual machine info and statistics
+Copyright (C) Red Hat Inc. 2009
+----------------------------------------------------------------------
+
+This README file is just an overview of the available documentation
+for virt-tools.
+
+To compile from source, see 'INSTALL'.
+
+To use and understand virt-tools, also including how it works and
+security considerations, see 'docs/virt-tools.pod' (which is installed
+as virt-tools(8) manpage).
+
+To hack on the code, see 'HACKING'.
+
+
+What is in each directory
+----------------------------------------------------------------------
+
+'[guest]' denotes something that is installed in the guest, and
+'[host]' denotes something that is install in the host.
+
+daemon/ [guest]
+ On Linux/Unix, this contains the configuration used to start the
+ virt-tools service *in the guest*. Note that the service is
+ just snmpd with a modified configuration. We don't include
+ the source for snmpd here -- that is supplied by another package
+ like net-snmp.
+
+docs/ [guest/host]
+
+ Man pages.
+
+linux/ [guest]
+
+ Linux-specific startup scripts for the guest.
+
+m4/
+
+ Autotools m4 macros.
+
+tools/ [host]
+
+ Source for the client tools.
+
+windows/ [guest]
+
+ Windows-specific configuration for the guest.
--- /dev/null
+mkdir -p m4
+autoreconf -i
+
+./configure "$@"
--- /dev/null
+# 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.
+
+AC_INIT([libguestfs],0.1.0)
+AM_INIT_AUTOMAKE([foreign])
+
+AC_CONFIG_MACRO_DIR([m4])
+
+AC_CHECK_PROG([PERL],[perl],[perl],[no])
+if test "x$PERL" = "xno"; then
+ AC_MSG_FAILURE([Perl must be installed])
+fi
+
+dnl Check for Perl modules that must be present to compile and
+dnl test the Perl bindings.
+missing_perl_modules=no
+required_perl_modules="Test::More Test::Pod Test::Pod::Coverage ExtUtils::MakeMaker Sys::Virt"
+optional_perl_modules="Sys::Guestfs"
+
+for pm in $required_perl_modules; do
+ AC_MSG_CHECKING([for $pm])
+ if ! $PERL -M$pm -e1 >/dev/null 2>&1; then
+ AC_MSG_RESULT([no])
+ missing_perl_modules=yes
+ else
+ AC_MSG_RESULT([yes])
+ fi
+done
+if test "x$missing_perl_modules" = "xyes"; then
+ AC_MSG_FAILURE([some Perl modules are missing])
+fi
+for pm in $optional_perl_modules; do
+ AC_MSG_CHECKING([for $pm])
+ if ! $PERL -M$pm -e1 >/dev/null 2>&1; then
+ AC_MSG_RESULT([no])
+ else
+ AC_MSG_RESULT([yes])
+ fi
+done
+
+dnl Check for pod2man and pod2text.
+AC_CHECK_PROG([POD2MAN],[pod2man],[pod2man],[no])
+test "x$POD2MAN" = "xno" &&
+ AC_MSG_ERROR([pod2man must be installed])
+AC_CHECK_PROG([POD2TEXT],[pod2text],[pod2text],[no])
+test "x$POD2TEXT" = "xno" &&
+ AC_MSG_ERROR([pod2text must be installed])
+
+AC_CONFIG_FILES([tools/virt-tools-get-key:tools/virt-tools-get-key.pl],
+ [chmod +x tools/virt-tools-get-key])
+AC_CONFIG_FILES([tools/virt-tools-get-transport:tools/virt-tools-get-transport.pl],
+ [chmod +x tools/virt-tools-get-transport])
+AC_CONFIG_FILES([tools/virt-uname:tools/virt-uname.pl],
+ [chmod +x tools/virt-uname])
+AC_CONFIG_FILES([tools/virt-ifconfig:tools/virt-ifconfig.pl],
+ [chmod +x tools/virt-ifconfig])
+AC_CONFIG_FILES([Makefile
+ daemon/Makefile docs/Makefile linux/Makefile tools/Makefile])
+AC_OUTPUT
--- /dev/null
+# 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.
--- /dev/null
+# 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
+
+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 $@
+
--- /dev/null
+=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<virt-uname> and C<virt-ps> 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</HOST TOOLS> section describes the client
+programs available to run on the host. The L</GUEST CONFIGURATION>
+section describes how to configure guests and secure the transport.
+
+Finally the L</ARCHITECTURE> 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<virt-tools-get-key> to get the secret key of the guest. (See
+L<virt-tools-get-key(8)> 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</etc/virt-tools/key> (in the guest) which is readable only by
+root.
+
+On Windows guests the secret key is written to
+C<%systemroot%\virttools.key>
+
+Using L<libguestfs(3)> the host can read any file in the guest, so it
+can read this secret key out directly. This is what the
+C<virt-tools-get-key> program does:
+
+ # virt-tools-get-key <name>
+ abcdef1234567890
+
+=head3 SECRET KEY CACHE
+
+C<virt-tools-get-key> 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</var/lib/virt-tools/keys/>.
+
+You can just delete the files in this directory at any time, I<or> you
+can drop a file in here which contains the secret key of a guest.
+
+To do this, create a file C</var/lib/virt-tools/keys/E<lt>UUIDE<gt>>
+where E<lt>UUIDE<gt> is the guest's UUID as displayed by this command:
+
+ virsh domuuid <name>
+
+The contents of the file should be the secret key.
+
+You can test this works by running C<virt-tools-get-key> by hand.
+
+=head2 DETERMINE TRANSPORT
+
+All the host tools use a second helper program called
+C<virt-tools-get-transport> to get the transport and address to use
+for a guest. (See L<virt-tools-get-transport(8)> 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 <name>
+ 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<rjones at redhat dot com>)
+
+=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.
--- /dev/null
+# 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.
--- /dev/null
+# 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-get-key.pl \
+ virt-tools-get-transport.pl \
+ virt-uname.pl \
+ virt-ifconfig.pl
+
+bin_SCRIPTS = \
+ virt-tools-get-key \
+ virt-tools-get-transport \
+ virt-uname \
+ virt-ifconfig
+
+# 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-ps
+
+install-exec-hook:
+ for prog in $(PROGS); do \
+ ln $(DESTDIR)$(bindir)/virt-uname $(DESTDIR)$(bindir)/$$prog; \
+ done
+
+man_MANS = virt-uname.8 $(PROGS:%=%.8)
+
+$(man_MANS):
+ rm -f $@-t
+ echo '.so man8/virt-tools.8' > $@-t
+ mv $@-t $@
+
+CLEANFILES = virt-uname.8 $(PROGS:%=%.8)
--- /dev/null
+#!/usr/bin/perl -w
+# 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.
+
+use Net::SNMP;
+
--- /dev/null
+#!/usr/bin/perl -w
+# 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.
+
+use Net::SNMP;
+
--- /dev/null
+#!/usr/bin/perl -w
+# 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.
+
+use Net::SNMP;
+
--- /dev/null
+#!/usr/bin/perl -w
+# 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.
+
+use Net::SNMP;
+
git.annexia.org / virt-tools.git / commitdiff