Add a man page for virtlockd daemon

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

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

diff --git a/.gitignore b/.gitignore
index faf82e408d2a6f8fadb5b84dd9f1e05568d1a2ec..6939527ab2ac3abff08d5fb2de2eccdeec7cb593 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -144,6 +144,8 @@
 /src/util/virkeymaps.h
 /src/virt-aa-helper
 /src/virtlockd
+/src/virtlockd.8
+/src/virtlockd.8.in
 /src/virtlockd.init
 /tests/*.log
 /tests/*.pid

diff --git a/libvirt.spec.in b/libvirt.spec.in
index 713511d4d540a30951c8a53f0ace5f874107c9d7..fc7de47ffd7ffd34a5e43cc081976c16ea955621 100644 (file)
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -1872,6 +1872,7 @@ fi
 %attr(0755, root, root) %{_sbindir}/virtlockd
 
 %{_mandir}/man8/libvirtd.8*
+%{_mandir}/man8/virtlockd.8*
 
     %if %{with_driver_modules}
         %if %{with_network}

diff --git a/src/Makefile.am b/src/Makefile.am
index 277f749c9471c354cbb3f27799d390ae45c424f5..d35153947b7a1a443645d2c262886d716c5556a8 100644 (file)
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -2019,9 +2019,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 (file)
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