Hostinfo day 1: Mainly documentation.

[virt-hostinfo.git] / hostinfo-set / hostinfo-set.pl

diff --git a/hostinfo-set/hostinfo-set.pl b/hostinfo-set/hostinfo-set.pl
new file mode 100755 (executable)
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<hostinfo(8)> 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<hostinfo(8)> 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<hostinfo(8)> 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<hostinfo-status(8)> command.
+
+See also:
+L<hostinfo-test(8)>,
+L<virt-install(1)>,
+L<virt-manager(1)>,
+L<http://fedoraproject.org/wiki/Features/Hostinfo>,
+L<http://libvirt.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 Red Hat Inc.
+L<http://fedoraproject.org/wiki/Features/Hostinfo>
+
+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.