From a318683c5b61719dcb6c73bbec4fbcf8b65ac31d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Date: Fri, 18 Oct 2019 15:29:47 +0100 Subject: [PATCH] docs: convert virtlockd man page from pod to rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was a semi-automated conversion. First it was run through pod2rst, and then it was manually editted to use a rst structure that matches expectations of rst2man. Reviewed-by: Cole Robinson Signed-off-by: Daniel P. Berrangé --- docs/Makefile.am | 2 + docs/manpages/index.rst | 1 + docs/manpages/virtlockd.rst | 177 ++++++++++++++++++++++++++++++++++++ src/locking/Makefile.inc.am | 18 ---- src/locking/virtlockd.pod | 165 --------------------------------- 5 files changed, 180 insertions(+), 183 deletions(-) create mode 100644 docs/manpages/virtlockd.rst delete mode 100644 src/locking/virtlockd.pod diff --git a/docs/Makefile.am b/docs/Makefile.am index dca976b470..5e8d667742 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -214,10 +214,12 @@ manpages_rst += \ if WITH_LIBVIRTD manpages8_rst += \ manpages/libvirtd.rst \ + manpages/virtlockd.rst \ $(NULL) else ! WITH_LIBVIRTD manpages_rst += \ manpages/libvirtd.rst \ + manpages/virtlockd.rst \ $(NULL) endif ! WITH_LIBVIRTD manpages_rst_html_in = \ diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 4467d88ba1..dc88cef198 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -6,3 +6,4 @@ Daemons ======= * `libvirtd(8) `__ - libvirt management daemon +* `virtlockd(8) `__ - libvirt lock management daemon diff --git a/docs/manpages/virtlockd.rst b/docs/manpages/virtlockd.rst new file mode 100644 index 0000000000..4066934e42 --- /dev/null +++ b/docs/manpages/virtlockd.rst @@ -0,0 +1,177 @@ +========= +virtlockd +========= + +------------------------------ +libvirt lock management daemon +------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +======== + +``virtlockd`` [*OPTION*]... + + +DESCRIPTION +=========== + +The ``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 ``libvirtd``. By maintaining the locks in a +standalone daemon, the main libvirtd daemon can be restarted without risk +of losing locks. The ``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. + + +OPTIONS +======= + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon and write PID file. + +``-f``, ``--config`` *FILE* + +Use this configuration file, overriding the default value. + +``-t``, ``--timeout`` *SECONDS* + +Automatically shutdown after *SECONDS* have elapsed with +no active client or lock. + +``-p``, ``--pid-file`` *FILE* + +Use this name for the PID file, overriding the default value. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``-V``, ``--version`` + +Display version information then exit. + +SIGNALS +======= + +On receipt of ``SIGUSR1``, ``virtlockd`` will re-exec() its binary, while +maintaining all current locks and clients. This allows for live +upgrades of the ``virtlockd`` service. + + +FILES +===== + +When run as *root* +------------------ + +* ``SYSCONFDIR/libvirt/virtlockd.conf`` + +The default configuration file used by ``virtlockd``, unless overridden on the +command line using the ``-f`` | ``--config`` option. + +* ``RUNSTATEDIR/libvirt/virtlockd-sock`` + +The sockets ``virtlockd`` will use. + +* ``RUNSTATEDIR/virtlockd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` option. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtlockd.conf`` + +The default configuration file used by ``virtlockd``, unless overridden on the +command line using the ``-f`` | ``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlockd-sock`` + +The socket ``virtlockd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlockd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` option. + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtlockd`` will use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtlockd`` will use +``$HOME/.cache`` + +EXAMPLES +======== + +To retrieve the version of ``virtlockd``: + +.. code-block:: shell + + # virtlockd --version + virtlockd (libvirt) 1.1.1 + +To start ``virtlockd``, instructing it to daemonize and create a PID file: + +.. code-block:: shell + + # virtlockd -d + # ls -la RUNSTATEDIR/virtlockd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 RUNSTATEDIR/virtlockd.pid + +BUGS +==== + +Please report all bugs you discover. This should be done via either: + +#. the mailing list + + `https://libvirt.org/contact.html `_ + +#. the bug tracker + + `https://libvirt.org/bugs.html `_ + +Alternatively, you may report bugs to your software distributor / vendor. + + +AUTHORS +======= + +Please refer to the AUTHORS file distributed with libvirt. + + +COPYRIGHT +========= + +Copyright (C) 2006-2013 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +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 + + +SEE ALSO +======== + +libvirtd(8), `https://libvirt.org/ `_ diff --git a/src/locking/Makefile.inc.am b/src/locking/Makefile.inc.am index 4f178a97ab..65b46ad5f3 100644 --- a/src/locking/Makefile.inc.am +++ b/src/locking/Makefile.inc.am @@ -70,12 +70,6 @@ CLEANFILES += \ RPC_PROBE_FILES += $(srcdir)/locking/lock_protocol.x SYSCONF_FILES += locking/virtlockd.sysconf -PODFILES += locking/virtlockd.pod -MANINFILES += virtlockd.8.in - -CLEANFILES += $(man8_MANS) -MAINTAINERCLEANFILES += $(MANINFILES) - VIRTLOCKD_UNIT_FILES_IN = \ locking/virtlockd.service.in \ locking/virtlockd.socket.in \ @@ -218,8 +212,6 @@ libvirt_sanlock_helper_LDFLAGS = \ libvirt_sanlock_helper_LDADD = libvirt.la endif WITH_SANLOCK -man8_MANS += virtlockd.8 - conf_DATA += locking/virtlockd.conf augeas_DATA += locking/virtlockd.aug @@ -294,13 +286,3 @@ virtlockd.socket: locking/virtlockd.socket.in $(top_builddir)/config.status virtlockd-admin.socket: locking/virtlockd-admin.socket.in \ $(top_builddir)/config.status $(AM_V_GEN)sed $(COMMON_UNIT_VARS) $< > $@-t && mv $@-t $@ - -virtlockd.8.in: locking/virtlockd.pod - $(AM_V_GEN)$(POD2MAN) --section=8 $< $@-t1 && \ - if grep 'POD ERROR' $@-t1; then rm $@-t1; exit 1; fi && \ - sed \ - -e 's|SYSCONFDIR|\@sysconfdir\@|g' \ - -e 's|RUNSTATEDIR|\@runstatedir\@|g' \ - < $@-t1 > $@-t2 && \ - rm -f $@-t1 && \ - mv $@-t2 $@ diff --git a/src/locking/virtlockd.pod b/src/locking/virtlockd.pod deleted file mode 100644 index 0b9f758e29..0000000000 --- a/src/locking/virtlockd.pod +++ /dev/null @@ -1,165 +0,0 @@ -=head1 NAME - -virtlockd - libvirt lock management daemon - -=head1 SYNOPSIS - -B [I