libvirtd: add man page for libvirtd

With gracious thanks to Chris Lalancette for helping knock the
description section into shape.

This addresses BZ #595350

  https://bugzilla.redhat.com/show_bug.cgi?id=595350

diff --git a/daemon/Makefile.am b/daemon/Makefile.am
index df34ef1a09842b3d5ba15ee0b73395980b0dd051..54012886af3a7c15cdec69d5e4a62800b42040c4 100644 (file)
--- a/daemon/Makefile.am
+++ b/daemon/Makefile.am
@@ -32,9 +32,12 @@ EXTRA_DIST =                                         \
        THREADING.txt                                   \
        libvirt-guests.init.in                          \
        libvirt-guests.sysconf                          \
+       libvirtd.pod.in                                 \
        $(AVAHI_SOURCES)                                \
        $(DAEMON_SOURCES)
 
+man_MANS = libvirtd.8
+
 BUILT_SOURCES =
 
 if WITH_LIBVIRTD
@@ -50,6 +53,20 @@ augeas_DATA = libvirtd.aug
 augeastestsdir = $(datadir)/augeas/lenses/tests
 augeastests_DATA = test_libvirtd.aug
 
+POD2MAN = pod2man -c "Virtualization Support" \
+                       -r "$(PACKAGE)-$(VERSION)" -s 8 -u
+
+libvirtd.pod: libvirtd.pod.in
+       sed \
+           -e 's![@]sysconfdir[@]!$(sysconfdir)!g' \
+           -e 's![@]localstatedir[@]!$(localstatedir)!g' \
+           -e 's![@]remote_pid_file[@]!$(REMOTE_PID_FILE)!g' \
+           < $< > $@-t
+       mv $@-t $@
+
+libvirtd.8: libvirtd.pod
+       $(AM_V_GEN)$(POD2MAN) $< $@
+
 libvirtd_SOURCES = $(DAEMON_SOURCES)
 
 #-D_XOPEN_SOURCE=600 -D_XOPEN_SOURCE_EXTENDED=1 -D_POSIX_C_SOURCE=199506L
@@ -285,5 +302,5 @@ uninstall-data-sasl:
 endif
 
 
-CLEANFILES = $(BUILT_SOURCES)
+CLEANFILES = $(BUILT_SOURCES) $(man_MANS) libvirtd.pod
 CLEANFILES += *.cov *.gcov .libs/*.gcda .libs/*.gcno *.gcno *.gcda

diff --git a/daemon/libvirtd.pod.in b/daemon/libvirtd.pod.in
new file mode 100644 (file)
index 0000000..9f578c4
--- /dev/null
+++ b/daemon/libvirtd.pod.in
@@ -0,0 +1,188 @@
+=encoding utf-8
+
+=head1 NAME
+
+libvirtd - libvirtd management daemon
+
+=head1 SYNOPSIS
+
+B<libvirtd> [ -dlv ] [ -f config_file ] [ -p pid_file ] [ -t timeout_seconds ]
+
+B<libvirtd> --version
+
+=head1 DESCRIPTION
+
+The B<libvirtd> program is the server side daemon component of the libvirt
+virtualization management system.
+
+This daemon runs on host servers and performs required management tasks for
+virtualized guests.  This includes activities such as starting, stopping
+and migrating guests between host servers, configuring and manipulating
+networking, and managing storage for use by guests.
+
+The libvirt client libraries and utilities connect to this daemon to issue
+tasks and collect information about the configuration and resources of the host
+system and guests.
+
+By default, the libvirtd daemon listens for requests on a local Unix domain
+socket.  Using the B<-l>|B<--listen> command line option, the libvirtd daemon
+can be instructed to additionally listen on a TCP/IP socket.  The TCP/IP socket
+to use is defined in the libvirtd configuration file.
+
+Restarting libvirtd does not impact running guests.  Guests continue to operate
+and will be picked up automatically if their XML configuration has been
+defined.  Any guests whose XML configuration has not been defined will be lost
+from the configuration.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-d, --daemon>
+
+Run as a daemon & write PID file.
+
+=item B<-f, --config> I<FILE>
+
+Use this configuration file, overriding the default value.
+
+=item B<-l, --listen>
+
+Listen for TCP/IP connections.
+
+=item B<-p, --pid-file> I<FILE>
+
+Use this name for the PID file, overriding the default value.
+
+=item B<-t, --timeout> I<SECONDS>
+
+Exit after timeout period (in seconds) expires.
+
+=item B<-v, --verbose>
+
+Enable output of verbose messages.
+
+=item B<    --version>
+
+Display version information then exit.
+
+=back
+
+=head1 SIGNALS
+
+On receipt of B<SIGHUP> libvirtd will reload its configuration.
+
+=head1 FILES
+
+=over
+
+=item F<@sysconfdir@/libvirtd.conf>
+
+The default configuration file used by libvirtd, unless overridden on the
+command line using the B<-f>|B<--config> option.
+
+=item F<@localstatedir@/run/libvirt/libvirt-sock>
+
+=item F<@localstatedir@/run/libvirt/libvirt-sock-ro>
+
+The sockets libvirtd will use when B<run as root>.
+
+=item F<$HOME/.libvirt/libvirt-sock>
+
+The socket libvirtd will use when run as a B<non-root> user.
+
+=item F<@sysconfdir@/pki/CA/cacert.pem>
+
+The TLS B<Certificate Authority> certificate libvirtd will use.
+
+=item F<@sysconfdir@/pki/libvirt/servercert.pem>
+
+The TLS B<Server> certificate libvirtd will use.
+
+=item F<@sysconfdir@/pki/libvirt/private/serverkey.pem>
+
+The TLS B<Server> private key libvirtd will use.
+
+=item F<@remote_pid_file@>
+
+The PID file to use, unless overridden by the B<-p>|B<--pid-file> option.
+
+=back
+
+=head1 EXAMPLES
+
+To retrieve the version of libvirtd:
+
+ # libvirtd --version
+ libvirtd (libvirt) 0.8.2
+ #
+
+To start libvirtd, instructing it to daemonize and create a PID file:
+
+ # libvirtd -d
+ # ls -la @remote_pid_file@
+ -rw-r--r-- 1 root root 6 Jul  9 02:40 @remote_pid_file@
+ #
+
+=head1 BUGS
+
+Please report all bugs you discover.  This should be done via either:
+
+=over
+
+=item a) the mailing list
+
+L<http://libvirt.org/contact.html>
+
+=item or,
+
+B<>
+
+=item b) the bug tracker
+
+L<http://libvirt.org/bugs.html>
+
+=item Alternatively, you may report bugs to your software distributor / vendor.
+
+=back
+
+=head1 AUTHORS
+
+ Stefan Berger        <stefanb@us.ibm.com>
+ Daniel Berrange      <berrange@redhat.com>
+ Eric Blake           <eblake@redhat.com>
+ Matthias Bolte       <matthias.bolte@googlemail.com>
+ Jiri Denemark        <jdenemar@redhat.com>
+ Amy Griffis          <amy.griffis@hp.com>
+ Guido Günther        <agx@sigxcpu.org>
+ Richard W.M. Jones   <rjones@redhat.com>
+ Dan Kenigsberg       <danken@redhat.com>
+ Chris Lalancette     <clalance@redhat.com>
+ Dave Leskovec        <dlesko@linux.vnet.ibm.com>
+ John Levon           <john.levon@sun.com>
+ Wolfgang Mauerer     <wolfgang.mauerer@siemens.com>
+ Mark McLoughlin      <markmc@redhat.com>
+ Jim Meyering         <meyering@redhat.com>
+ Cole Robinson        <crobinso@redhat.com>
+ Atsushi SAKAI        <sakaia@jp.fujitsu.com>
+ Laine Stump          <laine@redhat.com>
+ Miloslav Trmač       <mitr@redhat.com>
+ Daniel Veillard      <veillard@redhat.com> or <daniel@veillard.com>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2006-2010 Red Hat, Inc. and the above mentioned AUTHORS.
+
+=head1 LICENSE
+
+libvirtd is distributed under the terms of the GNU LGPL v2.1+.
+This is free software; see the source for copying conditions. There
+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE
+
+=head1 SEE ALSO
+
+L<virsh(1)>, L<virt-install(1)>, L<virt-xml-validate(1)>, L<virt-top(1)>,
+L<virt-mem(1)>, L<virt-df(1)>, L<http://www.libvirt.org/>
+
+=cut