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. Signed-off-by: Daniel P. Berrangé <berrange@xxxxxxxxxx> --- 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 8205f28788..6615915efb 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) <libvirtd.html>`__ - libvirt management daemon +* `virtlockd(8) <virtlockd.html>`__ - 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 <https://libvirt.org/contact.html>`_ + +#. the bug tracker + + `https://libvirt.org/bugs.html <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/ <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<virtlockd> [I<OPTION>]... - -=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<-h, --help> - -Display command line help usage then exit. - -=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<-t, --timeout> I<SECONDS> - -Automatically shutdown after I<SECONDS> have elapsed with -no active client or lock. - -=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<-V, --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/libvirt/virtlockd.conf> - -The default configuration file used by virtlockd, unless overridden on the -command line using the B<-f>|B<--config> option. - -=item F<RUNSTATEDIR/libvirt/virtlockd-sock> - -The sockets libvirtd will use. - -=item F<RUNSTATEDIR/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/libvirt/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 RUNSTATEDIR/virtlockd.pid - -rw-r--r-- 1 root root 6 Jul 9 02:40 RUNSTATEDIR/virtlockd.pid - # - -=head1 BUGS - -Please report all bugs you discover. This should be done via either: - -=over - -=item a) the mailing list - -L<https://libvirt.org/contact.html> - -=item or, - -B<> - -=item b) the bug tracker - -L<https://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<https://libvirt.org/> - -=cut -- 2.23.0 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
