From f09c4d7899108fe848baa71cde2f1b5d4199193b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Daniel=20P=2E=20Berrang=C3=A9?= Date: Fri, 18 Oct 2019 15:29:47 +0100 Subject: [PATCH] docs: convert virtlogd man page from pod to rst MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 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/virtlogd.rst | 179 ++++++++++++++++++++++++++++++++++++ src/logging/Makefile.inc.am | 13 --- src/logging/virtlogd.pod | 165 --------------------------------- 5 files changed, 182 insertions(+), 178 deletions(-) create mode 100644 docs/manpages/virtlogd.rst delete mode 100644 src/logging/virtlogd.pod diff --git a/docs/Makefile.am b/docs/Makefile.am index 5e8d667742..8ecfdc5307 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -215,11 +215,13 @@ if WITH_LIBVIRTD manpages8_rst += \ manpages/libvirtd.rst \ manpages/virtlockd.rst \ + manpages/virtlogd.rst \ $(NULL) else ! WITH_LIBVIRTD manpages_rst += \ manpages/libvirtd.rst \ manpages/virtlockd.rst \ + manpages/virtlogd.rst \ $(NULL) endif ! WITH_LIBVIRTD manpages_rst_html_in = \ diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index dc88cef198..8544fb2501 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -7,3 +7,4 @@ Daemons * `libvirtd(8) `__ - libvirt management daemon * `virtlockd(8) `__ - libvirt lock management daemon +* `virtlogd(8) `__ - libvirt log management daemon diff --git a/docs/manpages/virtlogd.rst b/docs/manpages/virtlogd.rst new file mode 100644 index 0000000000..7f4c5d7e7f --- /dev/null +++ b/docs/manpages/virtlogd.rst @@ -0,0 +1,179 @@ +======== +virtlogd +======== + +----------------------------- +libvirt log management daemon +----------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +======== + +``virtlogd`` [*OPTION*]... + + +DESCRIPTION +=========== + +The ``virtlogd`` program is a server side daemon component of the libvirt +virtualization management system that is used to manage logs from virtual +machine consoles. + +This daemon is not used directly by libvirt client applications, rather it +is called on their behalf by ``libvirtd``. By maintaining the logs in a +standalone daemon, the main libvirtd daemon can be restarted without risk +of losing logs. The ``virtlogd`` daemon has the ability to re-exec() +itself upon receiving SIGUSR1, to allow live upgrades without downtime. + +The ``virtlogd`` 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 console log. + +``-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``, ``virtlogd`` will re-exec() its binary, while +maintaining all current logs and clients. This allows for live +upgrades of the ``virtlogd`` service. + + +FILES +===== + +When run as *root* +------------------ + +* ``SYSCONFDIR/libvirt/virtlogd.conf`` + +The default configuration file used by ``virtlogd``, unless overridden on the +command line using the ``-f`` | ``--config`` option. + +* ``RUNSTATEDIR/libvirt/virtlogd-sock`` + +The sockets ``virtlogd`` will use. + +* ``RUNSTATEDIR/virtlogd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` option. + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtlogd.conf`` + +The default configuration file used by ``virtlogd``, unless overridden on the +command line using the ``-f`` | ``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlogd-sock`` + +The socket ``virtlogd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlogd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` option. + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtlogd`` will use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtlogd`` will use +``$HOME/.cache`` + + +EXAMPLES +======== + +To retrieve the version of ``virtlogd``: + +.. code-block:: shell + + # virtlogd --version + virtlogd (libvirt) 1.1.1 + +To start ``virtlogd``, instructing it to daemonize and create a PID file: + +.. code-block:: shell + + # virtlogd -d + # ls -la RUNSTATEDIR/virtlogd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 RUNSTATEDIR/virtlogd.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-2015 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +======= + +``virtlogd`` 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/logging/Makefile.inc.am b/src/logging/Makefile.inc.am index 12fc5c23c2..0f7ffa73b3 100644 --- a/src/logging/Makefile.inc.am +++ b/src/logging/Makefile.inc.am @@ -44,8 +44,6 @@ CLEANFILES += \ $(LOG_DAEMON_GENERATED) \ $(NULL) -PODFILES += logging/virtlogd.pod -MANINFILES += virtlogd.8.in SYSCONF_FILES += logging/virtlogd.sysconf VIRTLOGD_UNIT_FILES_IN = \ @@ -76,7 +74,6 @@ libvirt_driver_log_la_CFLAGS = \ if WITH_LIBVIRTD sbin_PROGRAMS += virtlogd -man8_MANS += virtlogd.8 virtlogd_SOURCES = \ $(LOG_DAEMON_SOURCES) \ @@ -131,16 +128,6 @@ logging/log_daemon_dispatch_stubs.h: $(LOG_PROTOCOL) \ virLogManagerProtocol VIR_LOG_MANAGER_PROTOCOL \ $(LOG_PROTOCOL) > logging/log_daemon_dispatch_stubs.h -virtlogd.8.in: logging/virtlogd.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 $@ - virtlogd.service: logging/virtlogd.service.in $(top_builddir)/config.status $(AM_V_GEN)sed $(COMMON_UNIT_VARS) $< > $@-t && mv $@-t $@ diff --git a/src/logging/virtlogd.pod b/src/logging/virtlogd.pod deleted file mode 100644 index 01dde99296..0000000000 --- a/src/logging/virtlogd.pod +++ /dev/null @@ -1,165 +0,0 @@ -=head1 NAME - -virtlogd - libvirt log management daemon - -=head1 SYNOPSIS - -B [I