[libvirt] [PATCH] Add a man page for virtlockd daemon

From: "Daniel P. Berrange" <berrange(a)redhat.com&gt; Create a virtlockd.pod.in file containing the man page content for virtlockd. Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com&gt; --- .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/.gitignore b/.gitignore index ae9de0b..26bd829 100644 --- 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 79c5a2c..a95b783 100644 --- 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 277f749..d351539 100644 --- 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 index 0000000..2621d2c --- /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 loosing 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 & 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.1