From: Richard W.M. Jones Date: Wed, 5 Aug 2009 11:43:28 +0000 (+0100) Subject: Hostinfo day 1: Mainly documentation. X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=b6184e540f0a61a014ccabc888530eb45458cfa2;p=virt-hostinfo.git Hostinfo day 1: Mainly documentation. --- diff --git a/.gitignore b/.gitignore index 2dac601..cc6cc7d 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,18 @@ config.h.in config.log config.status configure +conf/guests.conf +conf/hostinfo.conf depcomp +hostinfod/hostinfo.8 hostinfod/hostinfod +hostinfo-set/hostinfo-set.8 +hostinfo-set/hostinfo-set +hostinfo-status/hostinfo-status.8 +hostinfo-status/hostinfo-status +hostinfo-test/hostinfo-test.8 +hostinfo-test/hostinfo-test +localconfigure install-sh missing stamp-h1 diff --git a/Makefile.am b/Makefile.am index ac61ff1..859c7b9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -17,4 +17,4 @@ ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = hostinfod +SUBDIRS = hostinfod conf hostinfo-status hostinfo-set hostinfo-test diff --git a/README b/README index cd91204..2b8a7a8 100644 --- a/README +++ b/README @@ -12,8 +12,20 @@ http://fedoraproject.org/wiki/Features/Hostinfo Requirements ---------------------------------------------------------------------- +- C compiler + - APR (Apache Portable Runtime) 1.3 +- Perl + +- pod2man and other perldoc tools + * these are usually supplied with Perl + +- libvirt + +- Perl module Sys::Virt + + Build ---------------------------------------------------------------------- @@ -31,7 +43,7 @@ Host configuration ---------------------------------------------------------------------- You can edit the text configuration files under /etc/hostinfod by -hand. Please read the hostinfod(8) manual page. +hand. Please read the hostinfo(8) manual page. For graphical configuration, use virt-manager. diff --git a/conf/Makefile.am b/conf/Makefile.am new file mode 100644 index 0000000..cd63e78 --- /dev/null +++ b/conf/Makefile.am @@ -0,0 +1,20 @@ +# virt-hostinfo +# 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. + +confdir = $(sysconfdir)/hostinfo + +conf_DATA = hostinfo.conf guests.conf diff --git a/conf/guests.conf.in b/conf/guests.conf.in new file mode 100644 index 0000000..0e2cf31 --- /dev/null +++ b/conf/guests.conf.in @@ -0,0 +1,25 @@ +# Example per-guest configuration file for hostinfo daemon. +# See also '@sysconfdir@/hostinfo/hostinfo.conf'. + +# IMPORTANT: Please read hostinfo(8) manual page for documentation. + +# VERY IMPORTANT: If you change this file, then the daemon will notice +# the change next time it gets a request from a guest. HOWEVER for +# security reasons if you change this file and your change contains a +# mistake, then the DAEMON WILL EXIT with an error message (usually in +# syslog). Hostinfo defaults to no-access in these circumstances and +# you have to correct your mistake and restart the service ('service +# hostinfo restart'). + +# A rule for a specific qemu/KVM guest with the libvirt name 'dom'. +#[qemu-dom] +#interval 60 + +# A rule that would apply to all qemu/KVM guests. +#[qemu-*] +#interval 60 + +# Catch-all default rule for guests. This rule MUST be last in the file. +[*] +interval 1 +physcpus on diff --git a/conf/hostinfo.conf.in b/conf/hostinfo.conf.in new file mode 100644 index 0000000..aad6197 --- /dev/null +++ b/conf/hostinfo.conf.in @@ -0,0 +1,27 @@ +# Example configuration file for hostinfo daemon. +# See also '@sysconfdir@/hostinfo/guests.conf'. + +# IMPORTANT: Please read hostinfo(8) manual page for documentation. + +# This file contains any global configuration required by the +# hostinfo daemon. If you change this file, then you must +# restart the hostinfo service (ie. 'service hostinfo restart'). + +# Per-guest configuration is stored in a separate file. +# To configure what each guest can see, you have to edit +# this file, not the current file. +guests @sysconfdir@/hostinfo/guests.conf + +# Directory containing sockets which are used to communicate +# between the guests and the host. You probably shouldn't +# change this. +#sockets @localstatedir@/lib/hostinfo + +# Enable verbose messages sent to the system log files. +#verbose 1 + +# Don't fork into the background, and send verbose messages +# to stderr. You shouldn't normally enable this unless you +# are a developer. +#foreground 1 +#debug 1 diff --git a/configure.ac b/configure.ac index ba55b09..cbb64c7 100644 --- a/configure.ac +++ b/configure.ac @@ -36,7 +36,29 @@ AC_SYS_LARGEFILE dnl Check for required packages using pkg-config. PKG_CHECK_MODULES([HOSTINFOD],[apr-1 >= 1.3]) +dnl Check for Perl and POD. +AC_CHECK_PROG([PERL],[perl],[perl],[no]) +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]) + dnl Produce output files. AC_CONFIG_HEADERS([config.h]) -AC_CONFIG_FILES([Makefile hostinfod/Makefile]) +AC_CONFIG_FILES([Makefile + hostinfod/Makefile + conf/Makefile + conf/hostinfo.conf + conf/guests.conf + hostinfo-status/Makefile + hostinfo-set/Makefile + hostinfo-test/Makefile]) +AC_CONFIG_FILES([hostinfo-status/hostinfo-status:hostinfo-status/hostinfo-status.pl], + [chmod 0555 hostinfo-status/hostinfo-status]) +AC_CONFIG_FILES([hostinfo-set/hostinfo-set:hostinfo-set/hostinfo-set.pl], + [chmod 0555 hostinfo-set/hostinfo-set]) +AC_CONFIG_FILES([hostinfo-test/hostinfo-test:hostinfo-test/hostinfo-test.pl], + [chmod 0555 hostinfo-test/hostinfo-test]) AC_OUTPUT diff --git a/hostinfo-set/Makefile.am b/hostinfo-set/Makefile.am new file mode 100644 index 0000000..e9fe279 --- /dev/null +++ b/hostinfo-set/Makefile.am @@ -0,0 +1,29 @@ +# virt-hostinfo +# 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 = hostinfo-set.pl + +bin_SCRIPTS = hostinfo-set + +man_MANS = hostinfo-set.8 + +hostinfo-set.8: hostinfo-set + $(POD2MAN) \ + --section 8 \ + -c "Virtualization Support" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + $< > $@ diff --git a/hostinfo-set/hostinfo-set.pl b/hostinfo-set/hostinfo-set.pl new file mode 100755 index 0000000..8535cc6 --- /dev/null +++ b/hostinfo-set/hostinfo-set.pl @@ -0,0 +1,129 @@ +#!/usr/bin/perl -w +# @configure_input@ +# virt-hostinfo +# 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 strict; + +#use Sys::Virt; + +=pod + +=head1 NAME + +hostinfo-set - enable or disable hostinfo for a guest + +=head1 SYNOPSIS + + hostinfo-set [--options] [GUESTNAME [GUESTNAME...]] + + hostinfo-set --enable GUESTNAME [GUESTNAME...] + + hostinfo-set --disable GUESTNAME [GUESTNAME...] + +=head1 DESCRIPTION + +This command is used to enable or disable the L feature +per-guest. Note that you also need to enable the hostinfo service for +the host as a whole. You may also wish to configure what each guest +has access to. See L for information about how to do +that. + +The simplest use is to run this with C<--enable> or C<--disable> to +(respectively) enable or disable hostinfo for the libvirt guest(s) +named on the command line. For example: + + # virsh list --all + Id Name State + ---------------------------------- + 1 F11 running + - winxp shut off + + # hostinfo-set --enable F11 + +To enable hostinfo for every guest, you could do: + + hostinfo-set --enable --all + +=cut + + + +=head1 OPTIONS + +=over 4 + +=item B<--enable> + +Enable hostinfo per-guest for each of the guests listed on the command +line. + +=item B<--disable> + +Disable hostinfo per-guest for each of the guests listed on the command +line. + +Either C<--enable> or C<--disable> must be given. + +=item B<--all> + +If this option is given, then we try to enable or disable hostinfo for +every guest known to libvirt (both running and inactive). + +=back + +=cut + + + +=head1 SEE ALSO + +See the L manpage for the main documentation about +hostinfo configuration and troubleshooting. + +To see if hostinfo is enabled or disabled for a particular guest, use +the L command. + +See also: +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +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/hostinfo-status/Makefile.am b/hostinfo-status/Makefile.am new file mode 100644 index 0000000..d2e34e3 --- /dev/null +++ b/hostinfo-status/Makefile.am @@ -0,0 +1,29 @@ +# virt-hostinfo +# 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 = hostinfo-status.pl + +bin_SCRIPTS = hostinfo-status + +man_MANS = hostinfo-status.8 + +hostinfo-status.8: hostinfo-status + $(POD2MAN) \ + --section 8 \ + -c "Virtualization Support" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + $< > $@ diff --git a/hostinfo-status/hostinfo-status.pl b/hostinfo-status/hostinfo-status.pl new file mode 100755 index 0000000..b367206 --- /dev/null +++ b/hostinfo-status/hostinfo-status.pl @@ -0,0 +1,121 @@ +#!/usr/bin/perl -w +# @configure_input@ +# virt-hostinfo +# 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 strict; + +#use Sys::Virt; + +=pod + +=head1 NAME + +hostinfo-status - check if hostinfo is enabled for a guest + +=head1 SYNOPSIS + + hostinfo-status [GUESTNAME [GUESTNAME...]] + +=head1 DESCRIPTION + +This command finds out if hostinfo is enabled or disabled for a +particular guest. + +For example: + + # hostinfo-status myguest + myguest: hostinfo is enabled on serial port 1 (ttyS1/COM2) + +If no guest names are listed on the command line, this command +displays the status of all guests known to libvirt. + +If you want to find out if the hostinfo feature is enabled for the +host as a whole, you should use this command instead: + + service hostinfo status + +(see L). + +=cut + +=head1 OPTIONS + +=over 4 + +=item B<--quiet> + +Use this option from scripts to test if hostinfo is enabled +for a single guest without the verbose messages: + + if hostinfo-status --quiet myguest; then + echo Yes, hostinfo is enabled for this guest. + else + echo No, hostinfo is not enabled for this guest. + fi + +=back + +=cut + + + + +=head1 RETURN VALUE + +Normally C returns 0 if the command was successful, +or 2 if there was an error. + +However if you use the C<--quiet> option, it returns 0 if hostinfo +is enabled, 1 if hostinfo is disabled, or 2 if there was an error. + +=cut + + + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +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/hostinfo-test/Makefile.am b/hostinfo-test/Makefile.am new file mode 100644 index 0000000..fd206ad --- /dev/null +++ b/hostinfo-test/Makefile.am @@ -0,0 +1,29 @@ +# virt-hostinfo +# 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 = hostinfo-test.pl + +bin_SCRIPTS = hostinfo-test + +man_MANS = hostinfo-test.8 + +hostinfo-test.8: hostinfo-test + $(POD2MAN) \ + --section 8 \ + -c "Virtualization Support" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + $< > $@ diff --git a/hostinfo-test/hostinfo-test.pl b/hostinfo-test/hostinfo-test.pl new file mode 100755 index 0000000..8f9694e --- /dev/null +++ b/hostinfo-test/hostinfo-test.pl @@ -0,0 +1,95 @@ +#!/usr/bin/perl -w +# @configure_input@ +# virt-hostinfo +# 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 strict; + +#use Sys::Virt; + +=pod + +=head1 NAME + +hostinfo-test - make or test hostinfo requests from a virtual machine + +=head1 SYNOPSIS + + hostinfo-test [--options] + +=head1 DESCRIPTION + +I It only makes sense to use this command from inside +a guest (virtual machine). + +This command is used to make/test hostinfo requests. You can +use this to test that the hostinfo system is working end-to-end. + +On its own, the command will make a simple 'ping' request, just +to check that the path from the guest to the C (daemon) +inside the host is working: + + # hostinfo-test + +or: + + # hostinfo-test + error: no response ping request + +=cut + + + + + +=head1 RETURN VALUE + +This command returns 0 if the test succeeded, or 1 if the test failed +or there was an error. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +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/hostinfod/Makefile.am b/hostinfod/Makefile.am index 838c667..3f21ebe 100644 --- a/hostinfod/Makefile.am +++ b/hostinfod/Makefile.am @@ -15,8 +15,27 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +EXTRA_DIST = hostinfo.pod + sbin_PROGRAMS = hostinfod -hostinfod_SOURCES = main.c -hostinfod_CFLAGS = -Wall $(HOSTINFOD_CFLAGS) +hostinfod_SOURCES = \ + configuration.c \ + hostinfod.h \ + main.c + +hostinfod_CFLAGS = \ + -Wall \ + $(HOSTINFOD_CFLAGS) \ + -DDEFAULT_CONF_FILE=\"$(sysconfdir)/hostinfo/hostinfo.conf\" \ + -DDEFAULT_SOCKET_DIR=\"$(localstatedir)/lib/hostinfo\" hostinfod_LDADD = $(HOSTINFOD_LIBS) + +man_MANS = hostinfo.8 hostinfod.8 + +hostinfo.8: hostinfo.pod + $(POD2MAN) \ + --section 8 \ + -c "Virtualization Support" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + $< > $@ diff --git a/hostinfod/configuration.c b/hostinfod/configuration.c new file mode 100644 index 0000000..14a2b80 --- /dev/null +++ b/hostinfod/configuration.c @@ -0,0 +1,102 @@ +/* virt-hostinfo + * 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. + */ + +#ifdef HAVE_CONFIG_H +#include +#endif + +#include +#include +#include + +#include + +#include "hostinfod.h" + +typedef int (*process_line_fn) (const char *key, const char *value); +static void process_conf_file (const char *path, int exit_if_not_exist, process_line_fn process_line); + +/* Read the main configuration file. This file is NOT reread if it + * changes, but the auxiliary guests.conf file IS reread (and so is + * the socket directory of course). + */ +void +read_main_conf_file (void) +{ + process_conf_file (conf_file, 0, NULL); +} + +static void +process_conf_file (const char *path, int exit_if_not_exist, + process_line_fn process_line) +{ + static const char *whitespace = " \t\n\v"; + FILE *fp; + char *line = NULL; + size_t len = 0; + size_t real_len, key_len; + ssize_t r; + const char *key, *value; + + fp = fopen (path, "r"); + if (!fp) { + if (exit_if_not_exist) { + perror (path); + exit (1); + } + return; + } + + while ((r = getline (&line, &len, fp)) != -1) { + /* Remove trailing \n */ + real_len = len; + if (real_len > 0 && line[real_len-1] == '\n') + line[--real_len] = '\0'; + + /* Ignore blank lines and comments. */ + if (real_len == 0) + continue; + if (line[0] == '#' || strspn (line, whitespace) == real_len) + continue; + + /* Split into key value. */ + key_len = strcspn (line, whitespace); + line[key_len] = '\0'; + key = line; + value = key_len < real_len ? &line[key_len+1] : NULL; + if (value) { + value += strspn (line, whitespace); + if (value[0] == '\0') + value = NULL; + } + + if (process_line && process_line (key, value) == -1) + exit (1); + } + + free (line); + + if (ferror (fp)) { + fprintf (stderr, "error reading configuration file: %s\n", path); + exit (1); + } + if (fclose (fp) == EOF) { + perror (path); + exit (1); + } +} diff --git a/hostinfod/hostinfo.pod b/hostinfod/hostinfo.pod new file mode 100644 index 0000000..0f700eb --- /dev/null +++ b/hostinfod/hostinfo.pod @@ -0,0 +1,430 @@ +=encoding utf8 + +=head1 NAME + +hostinfo - allow controlled access to host information from virtual machines + +=head1 SYNOPSIS + + chkconfig hostinfo on + service hostinfo start + + chkconfig hostinfo off + service hostinfo stop + + chkconfig --list hostinfo + service hostinfo status + +=head1 DESCRIPTION + +This manpage describes running, configuring and troubleshooting the +hostinfo daemon and hostinfo service. For other parts of the hostinfo +system, see the other manpages listed under I at the end of +this document. + +The hostinfo service provides controlled access to host information +and statistics from virtual machines. + +The system administrator (of the host) must: + +=over 4 + +=item * + +explicitly enable the hostinfo feature, + +=item * + +select which virtual machines can see any data, + +=item * + +select which data they wish to disclose to virtual machines, and + +=item * + +select the frequency that virtual machines can ask for data. + +=back + +On the host side, information is collected and passed on by the +hostinfo daemon (C). If this daemon is not running then no +information at all can be disclosed to guests. + +Inside the guests, the information is made available through an +emulated serial port using a simple request-reply text-based protocol. +No special software or drivers are required inside the guest. + +=head2 ENABLE HOSTINFO FEATURE + +Enabling the hostinfo feature just means making sure the service +(ie. hostinfod) is running: + + chkconfig hostinfo on + service hostinfo start + +The C command ensures that the daemon is started +after the host boots. + +After the C command, C process should be running. +If it is not, check the system logfiles (eg. C or +C) and see the I section below. + +=head2 DISABLE HOSTINFO FEATURE + +To disable the hostinfo feature: + + chkconfig hostinfo off + service hostinfo stop + +The C command ensures the daemon will not start after the +host boots. + +=head2 CHECK STATUS OF HOSTINFO FEATURE + +This command will tell you if the hostinfo daemon will be started on +boot (and in which runlevels): + + chkconfig --list hostinfo + +The command will tell you if the daemon is currently running: + + service hostinfo status + +If the daemon is not running when you expect it to, check the system +logfiles (eg. C or C) and see the +I section below. + +=head2 ENABLE HOSTINFO FOR EACH GUEST + +In addition to enabling the hostinfo feature globally, the system +administrator I enable it for each guest. + +This can be done from L or L. + +You can also do it from the command line using the L +and L commands. + +See the relevant manpages for more information. + +=head1 CONFIGURATION + +All the configuration files described below can contain comments (any +line that starts with a C<#> character). Blank lines are ignored. + +In the discussion below, C means a boolean (truth value) which +can be one of: + +=over 4 + +=item B<1> + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +meaning true/on + +=item B<0> + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +meaning false/off. + +=back + +=head2 GENERAL CONFIGURATION: /etc/hostinfo/hostinfo.conf + +This file contains general configuration for the hostinfo daemon. + +Changes to this file are not detected automatically. After editing +this file, you must restart the hostinfo service: + + service hostinfo restart + +The settings which can be changed in C are: + +=over 4 + +=item B + +This contains the I to the C (per-guest +configuration file - see below). + +This setting is required, and the named C file must +exist. + +=item B + +This controls the path to the directory containing Unix domain +sockets, which are used for guest to host communication. Changing +this setting is I recommended, and doing so may cause guests to +be unable to communicate with the daemon. + +=item B + +If verbose is enabled, then lots of debug-type information is sent to +the system log files. This is useful for debugging configuration +problems, but not so good for production systems. + + + + + +=back + +=head2 PER-GUEST CONFIGURATION: /etc/hostinfo/guests.conf + +This file controls what information and statistics are disclosed to +each guest (virtual machine), and also how often guests are permitted +to request this information. Thus this file is very important to +controlling the security of the hostinfo system. + +Edits to this file take effect as soon as the next request is received +from any guest. You do not need to restart the daemon. + +B (ie. the default becomes no access). The reason for the error +will be sent to a system log file. So after editing this file, you +should check that hostinfo is available end-to-end (ie. from a guest), +else follow the I advice below. + +C contains a list of sections, with each section starting +with C<[hypervisor-guestname]>. The final section should be a +catch-all wildcard that matches any guest and gives the default rules +C<[*]>. A typical example would be: + + # Rule for specific qemu/KVM guest called 'guest1'. + [qemu-guest1] + interval 60 + physcpus off + + # Rule that covers all other qemu/KVM guests. + [qemu-*] + interval 60 + + # Catch-all default rule for guests. + # This rule MUST be last in the file. + [*] + interval 1 + physcpus on + #etc. + +In the section header, C<[hypervisor-guestname]>, the C +part refers to the name of the guest as it is known to libvirt. Use +the command C to show this. The C part +is the name of the libvirt driver, and is usually C for qemu and +KVM guests. Libvirt also uses this convention when naming log files, +so look in C if you are unsure of the fully +qualified names of your guests. As shown above, you can use +wildcards. + +I just configuring a guest in C I mean +that the guest will have access to host status. You also have to +enable the hostinfo feature globally, I enable it for that guest. +See above for how that is done. + +Within each section, you can configure the settings below. + +=over 4 + +=item B + +=item B + +This sets the maximum rate that a guest may request I piece of +information. The rate is expressed in seconds (which can be a +decimal), meaning the guest can make a request at most every N +seconds. + +Note: A guest can request each of the M pieces of information +available to it, every N seconds, which means in total there could up +to M requests every N seconds per guest. + +If a guest exceeds the rate at which it is allowed to make requests, +then the daemon sleeps before replying (just for that guest). + +Setting this to C means there is no limit. Guests can flood the +host with requests. + +=item B + +Enable or disable requesting the number of physical CPUs available in +the host. + + + + + + + +=back + +=head1 TROUBLESHOOTING + +=over 4 + +=item 1. + +Is the daemon running? + +Use C (on the host) to see if the daemon is +running. + +Also see if the C process appears in the process list: + + ps ax | grep hostinfod + +If the daemon is not running and/or will not start up, look in the +system log files for error messages. Depending on how L +or L are configured, these messages usually end up in +C or C. + +=item 2. + +Is hostinfo enabled for the guest? + +Use L and/or L to see if the +hostinfo feature is enabled for the guest and/or to enable it. + +You can also look to see if the serial port has been exported +to the guest by libvirt: + + virsh dumpxml guestname + +and look for the following fragment in the XML output (it may look +slightly different from that shown): + + + + + + +Note that the type will be C<'unix'> even for non-Unix guests. + +=item 3. + +Is the daemon configured to export information to the guest? + +Also, is the guest trying to request information too quickly? + +Look at the C configuration file, using the +guide above. + +You can also enable verbose messages in the daemon, which will send a +lot of information out to the system log files. You will be able to +trace each request as it comes in, and what the daemon decides to do +with it. To do this, set C in C, and then +restart the daemon. + +=item 4. + +Does the socket exist? + +Look for the communications socket in C +directory. + +A socket for the guest should exist. The socket should be +attached to the C process at one end, and the +C process at the other. Use this command to find out: + + netstat -anp + +If the socket doesn't exist or is not attached properly, this may +indicate a bug in hostinfo or qemu. + +=item 5. + +Can the guest request something? + +In the guest, disable any software which might try to make hostinfo +requests, then use the L program and see if you can +make requests. See that manpage for more information. + +=item 6. + +Are serial ports enabled in the guest? + +In the guest, make sure serial port drivers are enabled. + +For Linux and Unix-like guests, look through the output of the +L program to see if it found any serial ports. + +=item 7. + +Is the guest using the correct serial port? + +Use the L program in the guest to test this. + +=back + +=head1 FILES + +=over 4 + +=item /etc/hostinfo/hostinfo.conf + + +=item /etc/hostinfo/guests.conf + + +=item /var/lib/hostinfo/ + + + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +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/hostinfod/hostinfod.8 b/hostinfod/hostinfod.8 new file mode 100644 index 0000000..eaa3fd4 --- /dev/null +++ b/hostinfod/hostinfod.8 @@ -0,0 +1 @@ +.so man8/hostinfo.8 diff --git a/hostinfod/hostinfod.h b/hostinfod/hostinfod.h new file mode 100644 index 0000000..99a1efb --- /dev/null +++ b/hostinfod/hostinfod.h @@ -0,0 +1,40 @@ +/* virt-hostinfo + * 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. + */ + +#ifndef HOSTINFOD_H +#define HOSTINFOD_H + +#include + +/* main.c */ +extern const char *conf_file; +extern const char *socket_dir; +extern char *guests_file; +extern int socket_dir_set_on_cmdline; +extern int debug; +extern int debug_set_on_cmdline; +extern int verbose; +extern int verbose_set_on_cmdline; +extern int foreground; +extern int foreground_set_on_cmdline; +extern apr_pool_t *pool; /* pool for global memory allocation */ + +/* configuration.c */ +extern void read_main_conf_file (void); + +#endif /* HOSTINFOD_H */ diff --git a/hostinfod/main.c b/hostinfod/main.c index bb915ca..ad5b326 100644 --- a/hostinfod/main.c +++ b/hostinfod/main.c @@ -22,33 +22,99 @@ #include #include +#include #include #include #include -static void usage (void); +#include "hostinfod.h" + +const char *conf_file = DEFAULT_CONF_FILE; +const char *socket_dir = DEFAULT_SOCKET_DIR; +char *guests_file = NULL; +int socket_dir_set_on_cmdline = 0; +int debug = 0; +int debug_set_on_cmdline = 0; +int verbose = 0; +int verbose_set_on_cmdline = 0; +int foreground = 0; +int foreground_set_on_cmdline = 0; +apr_pool_t *pool = NULL; + +static void +usage (void) +{ + printf ("hostinfod (virt-hostinfo daemon)\n" + "Copyright (C) 2009 Red Hat Inc.\n" + "\n" + "Usage:\n" + " hostinfod [--options]\n" + "\n" + "Options:\n" + " --help Display full usage\n" + " -c file | --config file\n" + " Configuration file (default: %s)\n" + " -d | --debug Enable debug messages to stderr (implies -v)\n" + " -f | --foreground\n" + " Run in the foreground (don't fork)\n" + " -s dir | --socketdir dir\n" + " Socket directory (default: %s)\n" + " -v Enable verbose messages (sent to syslog, and to\n" + " stderr if -d option is given)\n", + DEFAULT_CONF_FILE, DEFAULT_SOCKET_DIR); +} int main (int argc, char *argv[]) { static const apr_getopt_option_t options[] = { + { "config", 'c', TRUE, "configuration file" }, + { "debug", 'd', FALSE, "enable debug messages to stderr" }, + { "foreground", 'f', FALSE, "run in foreground (don't fork)" }, + { "socketdir", 's', TRUE, "socket directory" }, + { "verbose", 'v', FALSE, "enable verbose messages" }, { "help", '?', FALSE, "display help" }, { NULL, 0, 0, NULL }, }; apr_status_t r; - apr_pool_t *mp; apr_getopt_t *opt; int c; const char *optarg; - + apr_initialize (); - apr_pool_create (&mp, NULL); + apr_pool_create (&pool, NULL); - apr_getopt_init (&opt, mp, argc, argv); + apr_getopt_init (&opt, pool, argc, argv); while ((r = apr_getopt_long (opt, options, &c, &optarg)) == APR_SUCCESS) { switch (c) { + case 'c': + conf_file = optarg; + /* If the user is specifying this on the command line, then + * it should exist. They may have typo'd the name. + */ + if (access (conf_file, R_OK) == -1) { + perror (conf_file); + exit (1); + } + break; + case 'd': + debug = verbose = 1; + debug_set_on_cmdline = verbose_set_on_cmdline = 1; + break; + case 'f': + foreground = 1; + foreground_set_on_cmdline = 1; + break; + case 's': + socket_dir = optarg; + socket_dir_set_on_cmdline = 1; + break; + case 'v': + verbose = 1; + verbose_set_on_cmdline = 1; + break; case '?': usage (); exit (0); @@ -61,21 +127,22 @@ main (int argc, char *argv[]) exit (1); } + read_main_conf_file (); + + + + + + + + + /* Daemonize. */ + chdir ("/"); + if (!foreground) + apr_proc_detach (1); + + + apr_terminate (); return 0; } - -static void -usage (void) -{ - printf ("hostinfod (virt-hostinfo daemon)\n" - "Copyright (C) 2009 Red Hat Inc.\n" - "\n" - "Usage:\n" - " hostinfod [-d] [-f]\n" - "\n" - "Options:\n" - " --help Display full usage\n" - " -d Enable verbose debug messages\n" - " -f Run in the foreground (don't fork)\n"); -}