From 782458a90679f6b3cf04c7a2090d45bff6adfc3b Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Mon, 24 Aug 2009 13:58:14 +0100 Subject: [PATCH] Build system. --- .gitignore | 15 ++++ INSTALL | 48 ++++++++++++ Makefile.am | 18 +++++ README | 48 ++++++++++++ autogen.sh | 4 + configure.ac | 73 ++++++++++++++++++ daemon/Makefile.am | 16 ++++ docs/Makefile.am | 30 ++++++++ docs/virt-tools.pod | 158 ++++++++++++++++++++++++++++++++++++++ linux/Makefile.am | 16 ++++ tools/Makefile.am | 47 ++++++++++++ tools/virt-ifconfig.pl | 20 +++++ tools/virt-tools-get-key.pl | 20 +++++ tools/virt-tools-get-transport.pl | 20 +++++ tools/virt-uname.pl | 20 +++++ 15 files changed, 553 insertions(+) create mode 100644 .gitignore create mode 100644 INSTALL create mode 100644 Makefile.am create mode 100755 autogen.sh create mode 100644 configure.ac create mode 100644 daemon/Makefile.am create mode 100644 docs/Makefile.am create mode 100644 docs/virt-tools.pod create mode 100644 linux/Makefile.am create mode 100644 tools/Makefile.am create mode 100755 tools/virt-ifconfig.pl create mode 100755 tools/virt-tools-get-key.pl create mode 100755 tools/virt-tools-get-transport.pl create mode 100755 tools/virt-uname.pl diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0736ca2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +*~ +*.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 diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..8ad654e --- /dev/null +++ b/INSTALL @@ -0,0 +1,48 @@ +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). diff --git a/Makefile.am b/Makefile.am new file mode 100644 index 0000000..f2f977c --- /dev/null +++ b/Makefile.am @@ -0,0 +1,18 @@ +# 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 diff --git a/README b/README index e69de29..d06586c 100644 --- a/README +++ b/README @@ -0,0 +1,48 @@ +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. diff --git a/autogen.sh b/autogen.sh new file mode 100755 index 0000000..8c57caa --- /dev/null +++ b/autogen.sh @@ -0,0 +1,4 @@ +mkdir -p m4 +autoreconf -i + +./configure "$@" diff --git a/configure.ac b/configure.ac new file mode 100644 index 0000000..adf06f3 --- /dev/null +++ b/configure.ac @@ -0,0 +1,73 @@ +# 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 diff --git a/daemon/Makefile.am b/daemon/Makefile.am new file mode 100644 index 0000000..770700f --- /dev/null +++ b/daemon/Makefile.am @@ -0,0 +1,16 @@ +# 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. diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..168c91c --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,30 @@ +# 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 $@ + diff --git a/docs/virt-tools.pod b/docs/virt-tools.pod new file mode 100644 index 0000000..5d751bb --- /dev/null +++ b/docs/virt-tools.pod @@ -0,0 +1,158 @@ +=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/linux/Makefile.am b/linux/Makefile.am new file mode 100644 index 0000000..770700f --- /dev/null +++ b/linux/Makefile.am @@ -0,0 +1,16 @@ +# 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. diff --git a/tools/Makefile.am b/tools/Makefile.am new file mode 100644 index 0000000..c45258b --- /dev/null +++ b/tools/Makefile.am @@ -0,0 +1,47 @@ +# 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) diff --git a/tools/virt-ifconfig.pl b/tools/virt-ifconfig.pl new file mode 100755 index 0000000..0b478b8 --- /dev/null +++ b/tools/virt-ifconfig.pl @@ -0,0 +1,20 @@ +#!/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; + diff --git a/tools/virt-tools-get-key.pl b/tools/virt-tools-get-key.pl new file mode 100755 index 0000000..0b478b8 --- /dev/null +++ b/tools/virt-tools-get-key.pl @@ -0,0 +1,20 @@ +#!/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; + diff --git a/tools/virt-tools-get-transport.pl b/tools/virt-tools-get-transport.pl new file mode 100755 index 0000000..0b478b8 --- /dev/null +++ b/tools/virt-tools-get-transport.pl @@ -0,0 +1,20 @@ +#!/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; + diff --git a/tools/virt-uname.pl b/tools/virt-uname.pl new file mode 100755 index 0000000..0b478b8 --- /dev/null +++ b/tools/virt-uname.pl @@ -0,0 +1,20 @@ +#!/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; + -- 1.8.3.1