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/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 6615915efb..9fa706f0a9 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) <libvirtd.html>`__ - libvirt management daemon * `virtlockd(8) <virtlockd.html>`__ - libvirt lock management daemon +* `virtlogd(8) <virtlogd.html>`__ - 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 <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-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/ <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<virtlogd> [I<OPTION>]... - -=head1 DESCRIPTION - -The B<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 B<libvirtd>. By maintaining the logs in a -standalone daemon, the main libvirtd daemon can be restarted without risk -of losing logs. The B<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. - -=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 console log. - -=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> virtlogd will re-exec() its binary, while -maintaining all current logs and clients. This allows for live -upgrades of the virtlogd service. - -=head1 FILES - -=head2 When run as B<root>. - -=over - -=item F<SYSCONFDIR/libvirt/virtlogd.conf> - -The default configuration file used by virtlogd, unless overridden on the -command line using the B<-f>|B<--config> option. - -=item F<RUNSTATEDIR/libvirt/virtlogd-sock> - -The sockets libvirtd will use. - -=item F<RUNSTATEDIR/virtlogd.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/virtlogd.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/virtlogd-sock> - -The socket libvirtd will use. - -=item F<$XDG_RUNTIME_DIR/libvirt/virtlogd.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 virtlogd: - - # virtlogd --version - virtlogd (libvirt) 1.1.1 - # - -To start virtlogd, instructing it to daemonize and create a PID file: - - # virtlogd -d - # ls -la RUNSTATEDIR/virtlogd.pid - -rw-r--r-- 1 root root 6 Jul 9 02:40 RUNSTATEDIR/virtlogd.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-2015 Red Hat, Inc., and the authors listed in the -libvirt AUTHORS file. - -=head1 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 - -=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
