[libvirt] [PATCH] libvirtd: add man page for libvirtd

From: Justin Clift <justin(a)salasaga.org&gt; 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 | 40 +++++++++++- daemon/libvirtd.pod.in | 168 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 207 insertions(+), 1 deletions(-) create mode 100644 daemon/libvirtd.pod.in diff --git a/daemon/Makefile.am b/daemon/Makefile.am index df34ef1..332e895 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,41 @@ augeas_DATA = libvirtd.aug augeastestsdir = $(datadir)/augeas/lenses/tests augeastests_DATA = test_libvirtd.aug +POD2MAN = pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)" -s 8 + +if WITH_REMOTE +libvirtd.pod: libvirtd.pod.in + sed \ + -e 's![@]sysconfdir[@]!$(sysconfdir)!g' \ + -e 's![@]localstatedir[@]!$(localstatedir)!g' \ + -e 's![@]tls_line1[@]!=item F<$(sysconfdir)/pki/CA/cacert.pem>!g' \ + -e 's![@]tls_line2[@]!The TLS B<Certificate Authority> certificate libvirtd will use.!g' \ + -e 's![@]tls_line3[@]!=item F<$(sysconfdir)/pki/libvirt/servercert.pem>!g' \ + -e 's![@]tls_line4[@]!The TLS B<Server> certificate libvirtd will use.!g' \ + -e 's![@]tls_line5[@]!=item F<$(sysconfdir)/pki/libvirt/private/serverkey.pem>!g' \ + -e 's![@]tls_line6[@]!The TLS B<Server> private key libvirtd will use.!g' \ + -e 's![@]remote_pid_file[@]!$(REMOTE_PID_FILE)!g' \ + < $< > $@-t + mv $@-t $@ +else +libvirtd.pod: libvirtd.pod.in + sed \ + -e 's![@]sysconfdir[@]!$(sysconfdir)!g' \ + -e 's![@]localstatedir[@]!$(localstatedir)!g' \ + -e 's![@]tls_line1[@]!!g' \ + -e 's![@]tls_line2[@]!!g' \ + -e 's![@]tls_line3[@]!!g' \ + -e 's![@]tls_line4[@]!!g' \ + -e 's![@]tls_line5[@]!!g' \ + -e 's![@]tls_line6[@]!!g' \ + -e 's![@]remote_pid_file[@]!$(REMOTE_PID_FILE)!g' \ + < $< > $@-t + mv $@-t $@ +endif + +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 +323,5 @@ uninstall-data-sasl: endif -CLEANFILES = $(BUILT_SOURCES) +CLEANFILES = $(BUILT_SOURCES) $(man1_MANS) 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 0000000..33437c9 --- /dev/null +++ b/daemon/libvirtd.pod.in @@ -0,0 +1,168 @@ +=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&lt;@sysconfdir(a)/libvirtd.conf&gt; + +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. + +@tls_line1@ + +@tls_line2@ + +@tls_line3@ + +@tls_line4@ + +@tls_line5@ + +@tls_line6@ + +=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 + + Andrew Puch <apuch @ redhat.com> + Daniel Veillard <veillard @ redhat.com> + +=head1 COPYRIGHT + +Copyright (C) 2010 Red Hat, Inc. + +=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 -- 1.7.1