From nobody Tue Nov 26 11:33:10 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575643929; cv=none; d=zohomail.com; s=zohoarc; b=D6pA35XKURcA0FY6Mg2qbeEmAXWXB995gM9s9MpgrHT1OLe+QFkZqCpuzMvr/cgD5TdOEdbOmDj8mmLdclLKdgI59jOqvTdn8/gbjjfVACyIe7IHg9+jNeTxL8oTlf0jf5MYPKoSKzFtXsqI2S+BSfkhRc4GiOUDP2d/aZS8cyk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575643929; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=BNqIWCkdwOXCaFoGWcGcGXyZl+heqnpqijhBoaE2v1U=; b=enNZg5LI1H4i22Ky11T+bRsH153IXgTKegbV0DJbOAsu0e26QWbJk8EE2RVMQ611PMrvcvS9h54DoOZhhDaX0t46cWdYv9Uf0IEIBMVfvVSicuTyFoc2EgEQYuY04gldg2q5VL6EEZI08BOFTscMwcqMryBAYooFRLbAAIQooy0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1575643929273563.930424559482; Fri, 6 Dec 2019 06:52:09 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-184-s77PLcqxOYm_B5wZYTFe8Q-1; Fri, 06 Dec 2019 09:51:24 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 90B6B800C74; Fri, 6 Dec 2019 14:51:18 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 669ED3B8; Fri, 6 Dec 2019 14:51:18 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 297846B4B8; Fri, 6 Dec 2019 14:51:18 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xB6EpEZu017027 for ; Fri, 6 Dec 2019 09:51:14 -0500 Received: by smtp.corp.redhat.com (Postfix) id 2AF395DA32; Fri, 6 Dec 2019 14:51:14 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-49.ams2.redhat.com [10.36.112.49]) by smtp.corp.redhat.com (Postfix) with ESMTP id D814C5D9E2; Fri, 6 Dec 2019 14:51:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1575643928; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=BNqIWCkdwOXCaFoGWcGcGXyZl+heqnpqijhBoaE2v1U=; b=NJLllGRNalSby2m5vC5ui6EnmA6MgPCsd/BOTmynjTIGFbAcp9KwjLkD9gHZjruxqqfCZg ZlZ/Z7+uaQ0OhzlkjC29fQh/3n/rQbtOa5rLMovkuaoNQqkYr7Un4j0dU5pBhCCpfPycJO buqvEztx/OaM9ecqtmSIYnrNiJB4lpU= From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Date: Fri, 6 Dec 2019 14:50:32 +0000 Message-Id: <20191206145042.3777845-8-berrange@redhat.com> In-Reply-To: <20191206145042.3777845-1-berrange@redhat.com> References: <20191206145042.3777845-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 07/17] docs: convert virtlockd man page from pod to rst X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-MC-Unique: s77PLcqxOYm_B5wZYTFe8Q-1 X-Mimecast-Spam-Score: 0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) 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=C3=A9 --- 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 +=3D \ if WITH_LIBVIRTD manpages8_rst +=3D \ manpages/libvirtd.rst \ + manpages/virtlockd.rst \ $(NULL) else ! WITH_LIBVIRTD manpages_rst +=3D \ manpages/libvirtd.rst \ + manpages/virtlockd.rst \ $(NULL) endif ! WITH_LIBVIRTD manpages_rst_html_in =3D \ 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 =3D=3D=3D=3D=3D=3D=3D =20 * `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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtlockd +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------ +libvirt lock management daemon +------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtlockd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 socke= t. + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-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 +=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D + +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`` opti= on. + + +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`` opti= on. + +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 +=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D + +Please refer to the AUTHORS file distributed with libvirt. + + +COPYRIGHT +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Copyright (C) 2006-2013 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D \ RPC_PROBE_FILES +=3D $(srcdir)/locking/lock_protocol.x SYSCONF_FILES +=3D locking/virtlockd.sysconf =20 -PODFILES +=3D locking/virtlockd.pod -MANINFILES +=3D virtlockd.8.in - -CLEANFILES +=3D $(man8_MANS) -MAINTAINERCLEANFILES +=3D $(MANINFILES) - VIRTLOCKD_UNIT_FILES_IN =3D \ locking/virtlockd.service.in \ locking/virtlockd.socket.in \ @@ -218,8 +212,6 @@ libvirt_sanlock_helper_LDFLAGS =3D \ libvirt_sanlock_helper_LDADD =3D libvirt.la endif WITH_SANLOCK =20 -man8_MANS +=3D virtlockd.8 - conf_DATA +=3D locking/virtlockd.conf =20 augeas_DATA +=3D locking/virtlockd.aug @@ -294,13 +286,3 @@ virtlockd.socket: locking/virtlockd.socket.in $(top_bu= ilddir)/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=3D8 $< $@-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 @@ -=3Dhead1 NAME - -virtlockd - libvirt lock management daemon - -=3Dhead1 SYNOPSIS - -B [I