From 69da992ba2381c0a8e49c5c05c3f8f5d3f0b5407 Mon Sep 17 00:00:00 2001

Message-Id: <69da992ba2381c0a8e49c5c05c3f8f5d3f0b5407.1377873638.git.jdenemar@redhat.com>

From: "Daniel P. Berrange" <berrange@redhat.com>

Date: Tue, 13 Aug 2013 11:35:59 +0100

Subject: [PATCH] Add a man page for virtlockd daemon

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

Create a virtlockd.pod.in file containing the man page

content for virtlockd.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>

(cherry picked from commit 6ff0cffd55dae2fa07e6e8dc844312a87946678c)

---

 .gitignore                   |   2 +

 libvirt.spec.in              |   1 +

 src/Makefile.am              |  24 ++++++-

 src/locking/virtlockd.pod.in | 158 +++++++++++++++++++++++++++++++++++++++++++

 4 files changed, 184 insertions(+), 1 deletion(-)

 create mode 100644 src/locking/virtlockd.pod.in

diff --git a/src/Makefile.am b/src/Makefile.am

index 62e427e..5a7e05a 100644

--- a/src/Makefile.am

+++ b/src/Makefile.am

@@ -1997,9 +1997,31 @@ virtlockd.init: locking/virtlockd.init.in $(top_builddir)/config.status

 	    chmod a+x $@-t &&					\

 	    mv $@-t $@

+POD2MAN = pod2man -c "Virtualization Support" \

+			-r "$(PACKAGE)-$(VERSION)" -s 8

+$(srcdir)/virtlockd.8.in: locking/virtlockd.pod.in $(top_srcdir)/configure.ac

+	$(AM_V_GEN)$(POD2MAN) --name VIRTLOCKD $< $@ \

+	    && if grep 'POD ERROR' $@ ; then rm $@; exit 1; fi

+

+virtlockd.8: $(srcdir)/virtlockd.8.in

+	$(AM_V_GEN)sed \

+	    -e 's|[@]sysconfdir[@]|$(sysconfdir)|g' \

+	    -e 's|[@]localstatedir[@]|$(localstatedir)|g' \

+	    < $< > $@-t && \

+	mv $@-t $@

+

+man8_MANS = virtlockd.8

+

+MAINTAINERCLEANFILES += $(srcdir)/virtlockd.8.in

+

+EXTRA_DIST += \

+        locking/virtlockd.service.in \

+        locking/virtlockd.socket.in \

+        locking/virtlockd.pod.in \

+        virtlockd.8.in \

+        $(NULL)

-EXTRA_DIST += locking/virtlockd.service.in locking/virtlockd.socket.in

 if WITH_LIBVIRTD

 if LIBVIRT_INIT_SCRIPT_SYSTEMD

diff --git a/src/locking/virtlockd.pod.in b/src/locking/virtlockd.pod.in

new file mode 100644

index 0000000..f5748ca

--- /dev/null

+++ b/src/locking/virtlockd.pod.in

@@ -0,0 +1,158 @@

+=head1 NAME

+

+virtlockd - libvirt lock management daemon

+

+=head1 SYNOPSIS

+

+B<virtlockd> [ -dv ] [ -f config_file ] [ -p pid_file ]

+

+B<virtlockd> --version

+

+=head1 DESCRIPTION

+

+The B<virtlockd> program is a server side daemon component of the libvirt

+virtualization management system that is used to manage locks held against

+virtual machine resources, such as their disks.

+

+This daemon is not used directly by libvirt client applications, rather it

+is called on their behalf by B<libvirtd>. By maintaining the locks in a

+standalone daemon, the main libvirtd daemon can be restarted without risk

+of losing locks.  The B<virtlockd> daemon has the ability to re-exec()

+itself upon receiving SIGUSR1, to allow live upgrades without downtime.

+

+The virtlockd daemon listens for requests on a local Unix domain socket.

+

+=head1 OPTIONS

+

+=over

+

+=item B<-d, --daemon>

+

+Run as a daemon and write PID file.

+

+=item B<-f, --config> I<FILE>

+

+Use this configuration file, overriding the default value.

+

+=item B<-p, --pid-file> I<FILE>

+

+Use this name for the PID file, overriding the default value.

+

+=item B<-v, --verbose>

+

+Enable output of verbose messages.

+

+=item B<    --version>

+

+Display version information then exit.

+

+=back

+

+=head1 SIGNALS

+

+On receipt of B<SIGUSR1> virtlockd will re-exec() its binary, while

+maintaining all current locks and clients. This allows for live

+upgrades of the virtlockd service.

+

+=head1 FILES

+

+=head2 When run as B<root>.

+

+=over

+

+=item F<SYSCONFDIR/virtlockd.conf>

+

+The default configuration file used by virtlockd, unless overridden on the

+command line using the B<-f>|B<--config> option.

+

+=item F<LOCALSTATEDIR/run/libvirt/virtlockd-sock>

+

+The sockets libvirtd will use.

+

+=item F<LOCALSTATEDIR/run/virtlockd.pid>

+

+The PID file to use, unless overridden by the B<-p>|B<--pid-file> option.

+

+=back

+

+=head2 When run as B<non-root>.

+

+=over

+

+=item F<$XDG_CONFIG_HOME/virtlockd.conf>

+

+The default configuration file used by libvirtd, unless overridden on the

+command line using the B<-f>|B<--config> option.

+

+=item F<$XDG_RUNTIME_DIR/libvirt/virtlockd-sock>

+

+The socket libvirtd will use.

+

+=item F<$XDG_RUNTIME_DIR/libvirt/virtlockd.pid>

+

+The PID file to use, unless overridden by the B<-p>|B<--pid-file> option.

+

+=item If $XDG_CONFIG_HOME is not set in your environment, libvirtd will use F<$HOME/.config>

+

+=item If $XDG_RUNTIME_DIR is not set in your environment, libvirtd will use F<$HOME/.cache>

+

+=back

+

+=head1 EXAMPLES

+

+To retrieve the version of virtlockd:

+

+ # virtlockd --version

+ virtlockd (libvirt) 1.1.1

+ #

+

+To start virtlockd, instructing it to daemonize and create a PID file:

+

+ # virtlockd -d

+ # ls -la LOCALSTATEDIR/run/virtlockd.pid

+ -rw-r--r-- 1 root root 6 Jul  9 02:40 LOCALSTATEDIR/run/virtlockd.pid

+ #

+

+=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

+

+Please refer to the AUTHORS file distributed with libvirt.

+

+=head1 COPYRIGHT

+

+Copyright (C) 2006-2013 Red Hat, Inc., and the authors listed in the

+libvirt AUTHORS file.

+

+=head1 LICENSE

+

+virtlockd 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<libvirtd(8)>,  L<http://www.libvirt.org/>

+

+=cut

-- 

1.8.3.2