From c6a6dc1d2d04b1d5aeb6978577f4d08a216f93ed Mon Sep 17 00:00:00 2001 From: Justin Clift Date: Fri, 9 Jul 2010 19:21:39 +1000 Subject: [PATCH] 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 --- daemon/Makefile.am | 19 ++++- daemon/libvirtd.pod.in | 188 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 daemon/libvirtd.pod.in diff --git a/daemon/Makefile.am b/daemon/Makefile.am index df34ef1a09..54012886af 100644 --- 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 index 0000000000..9f578c48a1 --- /dev/null +++ b/daemon/libvirtd.pod.in @@ -0,0 +1,188 @@ +=encoding utf-8 + +=head1 NAME + +libvirtd - libvirtd management daemon + +=head1 SYNOPSIS + +B [ -dlv ] [ -f config_file ] [ -p pid_file ] [ -t timeout_seconds ] + +B --version + +=head1 DESCRIPTION + +The B 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 + +Use this configuration file, overriding the default value. + +=item B<-l, --listen> + +Listen for TCP/IP connections. + +=item B<-p, --pid-file> I + +Use this name for the PID file, overriding the default value. + +=item B<-t, --timeout> I + +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 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. + +=item F<$HOME/.libvirt/libvirt-sock> + +The socket libvirtd will use when run as a B user. + +=item F<@sysconfdir@/pki/CA/cacert.pem> + +The TLS B certificate libvirtd will use. + +=item F<@sysconfdir@/pki/libvirt/servercert.pem> + +The TLS B certificate libvirtd will use. + +=item F<@sysconfdir@/pki/libvirt/private/serverkey.pem> + +The TLS B 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 + +=item or, + +B<> + +=item b) the bug tracker + +L + +=item Alternatively, you may report bugs to your software distributor / vendor. + +=back + +=head1 AUTHORS + + Stefan Berger + Daniel Berrange + Eric Blake + Matthias Bolte + Jiri Denemark + Amy Griffis + Guido Günther + Richard W.M. Jones + Dan Kenigsberg + Chris Lalancette + Dave Leskovec + John Levon + Wolfgang Mauerer + Mark McLoughlin + Jim Meyering + Cole Robinson + Atsushi SAKAI + Laine Stump + Miloslav Trmač + Daniel Veillard or + +=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, L, L, L, +L, L, L + +=cut