From 69da992ba2381c0a8e49c5c05c3f8f5d3f0b5407 Mon Sep 17 00:00:00 2001 Message-Id: <69da992ba2381c0a8e49c5c05c3f8f5d3f0b5407.1377873638.git.jdenemar@redhat.com> From: "Daniel P. Berrange" 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 (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 [ -dv ] [ -f config_file ] [ -p pid_file ] + +B --version + +=head1 DESCRIPTION + +The B 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. By maintaining the locks in a +standalone daemon, the main libvirtd daemon can be restarted without risk +of losing locks. The B 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 + +Use this configuration file, overriding the default value. + +=item B<-p, --pid-file> I + +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 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. + +=over + +=item F + +The default configuration file used by virtlockd, unless overridden on the +command line using the B<-f>|B<--config> option. + +=item F + +The sockets libvirtd will use. + +=item F + +The PID file to use, unless overridden by the B<-p>|B<--pid-file> option. + +=back + +=head2 When run as B. + +=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 + +=item or, + +B<> + +=item b) the bug tracker + +L + +=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, L + +=cut -- 1.8.3.2