From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632591; cv=none; d=zohomail.com; s=zohoarc; b=f5oYwMmndq68zw7QUXjL66URhH/ZwG9DNFZESYZcn9QF8IDN6ScTyKVecIvEZlTifsHrHT0wMNkgxBL8/BsvxMCrzYOPnu0avW6xjbWhg2pXsN+Rz9tvMzZELWeADKxegopaqd4FUON+UQ9GcZw4jWp6Uo7IZAWs5dBaM1NB738= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632591; 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=BCO3MgzYlubLFZFcQl8Vqze3QqN3/hdKte9Ev0PmPKw=; b=XQRr617Rqg+mYBqY2u5It22xebSQeO3DORaFxfHdu8gohcNrRZlPyMXo4IT4l1Q5/JVdpVAcO7g6rze1THtomg4rvvP1+XpI1o92kXdWfF0bkVPFO06Uy0r84tPJ0dm4uUTLjVnX3QqlkptVlfbKXBgeD2BVdym8d8R/7He9Sik= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632590689396.6885766020563; Tue, 17 Nov 2020 09:03:10 -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-463-db1hf9ZVMe6xtaml3MVO2g-1; Tue, 17 Nov 2020 12:02:46 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 59A2E1882FBB; Tue, 17 Nov 2020 17:02:40 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 31F765B4CF; Tue, 17 Nov 2020 17:02:40 +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 E92321832FE0; Tue, 17 Nov 2020 17:02:39 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAVko027955 for ; Tue, 17 Nov 2020 11:10:31 -0500 Received: by smtp.corp.redhat.com (Postfix) id F36BB5B4BE; Tue, 17 Nov 2020 16:10:30 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 175285B4CF; Tue, 17 Nov 2020 16:10:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632588; 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=BCO3MgzYlubLFZFcQl8Vqze3QqN3/hdKte9Ev0PmPKw=; b=go7FGGQZ6vP1/BQATuQWrRoy+772kBgybe25sw9SReZq9xWcI1cMuJyIbOHKsWQt0tQag+ 0nYj/eSLi3jd8N21S5CKAQRiO22RZ6GCLFisAwvYM7xxVgHbsFUGbxIS7IJAq1HzvR6UkF Fe9gus/IvPQNd6wU64Pc+TmUoLSnbzU= X-MC-Unique: db1hf9ZVMe6xtaml3MVO2g-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 01/16] docs: consistently mark libvirtd as preformatted text Date: Tue, 17 Nov 2020 16:10:12 +0000 Message-Id: <20201117161027.210543-2-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/libvirtd.rst | 48 +++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/manpages/libvirtd.rst b/docs/manpages/libvirtd.rst index cd9976c5e4..2ce6284b3a 100644 --- a/docs/manpages/libvirtd.rst +++ b/docs/manpages/libvirtd.rst @@ -32,13 +32,13 @@ The libvirt client libraries and utilities connect to t= his daemon to issue tasks and collect information about the configuration and resources of the= host system and guests. =20 -By default, the libvirtd daemon listens for requests on a local Unix domain -socket. Using the ``-l`` | ``--listen`` command line option, the libvirtd= daemon -can be instructed to additionally listen on a TCP/IP socket. The TCP/IP s= ocket -to use is defined in the libvirtd configuration file. +By default, the ``libvirtd`` daemon listens for requests on a local Unix d= omain +socket. Using the ``-l`` | ``--listen`` command line option, the ``libvir= td`` +daemon can be instructed to additionally listen on a TCP/IP socket. The T= CP/IP +socket to use is defined in the ``libvirtd`` configuration file. =20 -Restarting libvirtd does not impact running guests. Guests continue to op= erate -and will be picked up automatically if their XML configuration has been +Restarting ``libvirtd`` does not impact running guests. Guests continue to +operate and will be picked up automatically if their XML configuration has= been defined. Any guests whose XML configuration has not been defined will be = lost from the configuration. =20 @@ -98,8 +98,8 @@ Use this configuration file, overriding the default value. ``-l``, ``--listen`` =20 Listen for TCP/IP connections. This should not be set if using systemd -socket activation. Instead activate the libvirtd-tls.socket or -libvirtd-tcp.socket unit files. +socket activation. Instead activate the ``libvirtd-tls.socket`` or +``libvirtd-tcp.socket`` unit files. =20 ``-p``, ``--pid-file *FILE*`` =20 @@ -122,7 +122,7 @@ Display version information then exit. SIGNALS =3D=3D=3D=3D=3D=3D=3D =20 -On receipt of ``SIGHUP`` libvirtd will reload its configuration. +On receipt of ``SIGHUP`` ``libvirtd`` will reload its configuration. =20 =20 FILES @@ -133,25 +133,25 @@ When run as *root* =20 * ``@SYSCONFDIR@/libvirt/libvirtd.conf`` =20 -The default configuration file used by libvirtd, unless overridden on the +The default configuration file used by ``libvirtd``, unless overridden on = the command line using the ``-f`` | ``--config`` option. =20 * ``@RUNSTATEDIR@/libvirt/libvirt-sock`` * ``@RUNSTATEDIR@/libvirt/libvirt-sock-ro`` =20 -The sockets libvirtd will use. +The sockets ``libvirtd`` will use. =20 * ``@SYSCONFDIR@/pki/CA/cacert.pem`` =20 -The TLS **Certificate Authority** certificate libvirtd will use. +The TLS **Certificate Authority** certificate ``libvirtd`` will use. =20 * ``@SYSCONFDIR@/pki/libvirt/servercert.pem`` =20 -The TLS **Server** certificate libvirtd will use. +The TLS **Server** certificate ``libvirtd`` will use. =20 * ``@SYSCONFDIR@/pki/libvirt/private/serverkey.pem`` =20 -The TLS **Server** private key libvirtd will use. +The TLS **Server** private key ``libvirtd`` will use. =20 * ``@RUNSTATEDIR@/libvirtd.pid`` =20 @@ -163,41 +163,41 @@ When run as *non-root* =20 * ``$XDG_CONFIG_HOME/libvirt/libvirtd.conf`` =20 -The default configuration file used by libvirtd, unless overridden on the +The default configuration file used by ``libvirtd``, unless overridden on = the command line using the ``-f``|``--config`` option. =20 * ``$XDG_RUNTIME_DIR/libvirt/libvirt-sock`` =20 -The socket libvirtd will use. +The socket ``libvirtd`` will use. =20 * ``$HOME/.pki/libvirt/cacert.pem`` =20 -The TLS **Certificate Authority** certificate libvirtd will use. +The TLS **Certificate Authority** certificate ``libvirtd`` will use. =20 * ``$HOME/.pki/libvirt/servercert.pem`` =20 -The TLS **Server** certificate libvirtd will use. +The TLS **Server** certificate ``libvirtd`` will use. =20 * ``$HOME/.pki/libvirt/serverkey.pem`` =20 -The TLS **Server** private key libvirtd will use. +The TLS **Server** private key ``libvirtd`` will use. =20 * ``$XDG_RUNTIME_DIR/libvirt/libvirtd.pid`` =20 The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. =20 =20 -If ``$XDG_CONFIG_HOME`` is not set in your environment, libvirtd will use +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``libvirtd`` will = use ``$HOME/.config`` =20 -If ``$XDG_RUNTIME_DIR`` is not set in your environment, libvirtd will use +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``libvirtd`` will = use ``$HOME/.cache`` =20 =20 EXAMPLES =3D=3D=3D=3D=3D=3D=3D=3D =20 -To retrieve the version of libvirtd: +To retrieve the version of ``libvirtd``: =20 :: =20 @@ -205,7 +205,7 @@ To retrieve the version of libvirtd: libvirtd (libvirt) 0.8.2 =20 =20 -To start libvirtd, instructing it to daemonize and create a PID file: +To start ``libvirtd``, instructing it to daemonize and create a PID file: =20 :: =20 @@ -246,7 +246,7 @@ libvirt AUTHORS file. LICENSE =3D=3D=3D=3D=3D=3D=3D =20 -libvirtd is distributed under the terms of the GNU LGPL v2.1+. +``libvirtd`` 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 --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632575; cv=none; d=zohomail.com; s=zohoarc; b=baBmT8qaKEc1W2NqJOjM2cLkynH0BWEpIBXTdpamgBsqC+MWQOQWyQGiCrLM5PiboO6kB2UxJE62gq2NKUFwKbHBqVbpmJs8BUAvkN1MKKCsYM0SMTB8xk+cMOnLrA41uI1FHxUVtP+kNXpyzXNKIw/GKyxKN+71AjaYt60vlP8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632575; 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=Rs2QuGL+5rb9BT51NBiEAkvp2Al+cfNvTCABJupf1EA=; b=icOyG6zApPxwi85y1CRHW33+WbXzLBBRDYpx+njRnkGFD12tu7q+crYPttCMGVOdMZGma26vn0ZvHILsvVspyQfARuOpAacaXoXxFQusbBTYkh/Bt20e1h0N9rq+fvqNnWohFPBx5wX8a2xiGv/jucooedMUupTffnQDBvktVTI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632575094572.491621219743; Tue, 17 Nov 2020 09:02:55 -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-346-XmEWaJmvMAyvmzwHfLgoRA-1; Tue, 17 Nov 2020 12:02:49 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5014211CC7E2; Tue, 17 Nov 2020 17:02:43 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2CF0160C43; Tue, 17 Nov 2020 17:02:43 +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 E60941832FE2; Tue, 17 Nov 2020 17:02:42 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAW8a027966 for ; Tue, 17 Nov 2020 11:10:32 -0500 Received: by smtp.corp.redhat.com (Postfix) id 32EBA5B4C8; Tue, 17 Nov 2020 16:10:32 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 60B8C5B4BE; Tue, 17 Nov 2020 16:10:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632572; 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=Rs2QuGL+5rb9BT51NBiEAkvp2Al+cfNvTCABJupf1EA=; b=isLuYNpFaXr3smy6IvT0ePEtr36ty57A9BSgGdLT9fO7aRbKYsGSQRJjfl60f/ZttX4i56 O0NVluIc4sZ+AXYNYKeGdjk1UFoKEQYBYLZwImxpr8NxWFTnPlUtRi4hcETMnhCfNGoMTJ w2TtsY6c/hnFebLB7WRg3rHOFpUSDss= X-MC-Unique: XmEWaJmvMAyvmzwHfLgoRA-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 02/16] docs: don't hardcode an ancient version in manpage examples Date: Tue, 17 Nov 2020 16:10:13 +0000 Message-Id: <20201117161027.210543-3-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Subsitute in the current version so the example always reflect today's version of reality. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/libvirtd.rst | 2 +- docs/manpages/meson.build | 1 + docs/manpages/virtlockd.rst | 2 +- docs/manpages/virtlogd.rst | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/manpages/libvirtd.rst b/docs/manpages/libvirtd.rst index 2ce6284b3a..ed591f4778 100644 --- a/docs/manpages/libvirtd.rst +++ b/docs/manpages/libvirtd.rst @@ -202,7 +202,7 @@ To retrieve the version of ``libvirtd``: :: =20 # libvirtd --version - libvirtd (libvirt) 0.8.2 + libvirtd (libvirt) @VERSION@ =20 =20 To start ``libvirtd``, instructing it to daemonize and create a PID file: diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 7156c10cc6..f6388b6262 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -71,6 +71,7 @@ endforeach docs_man_conf =3D configuration_data() docs_man_conf.set('SYSCONFDIR', sysconfdir) docs_man_conf.set('RUNSTATEDIR', runstatedir) +docs_man_conf.set('VERSION', meson.project_version()) =20 foreach data : docs_man_files rst_in_file =3D '@0@.rst'.format(data['name']) diff --git a/docs/manpages/virtlockd.rst b/docs/manpages/virtlockd.rst index 8ca231d14f..0bbee5a5f7 100644 --- a/docs/manpages/virtlockd.rst +++ b/docs/manpages/virtlockd.rst @@ -123,7 +123,7 @@ To retrieve the version of ``virtlockd``: :: =20 # virtlockd --version - virtlockd (libvirt) 1.1.1 + virtlockd (libvirt) @VERSION@ =20 To start ``virtlockd``, instructing it to daemonize and create a PID file: =20 diff --git a/docs/manpages/virtlogd.rst b/docs/manpages/virtlogd.rst index 4b749fe18e..1e39ff1b49 100644 --- a/docs/manpages/virtlogd.rst +++ b/docs/manpages/virtlogd.rst @@ -124,7 +124,7 @@ To retrieve the version of ``virtlogd``: :: =20 # virtlogd --version - virtlogd (libvirt) 1.1.1 + virtlogd (libvirt) @VERSION@ =20 To start ``virtlogd``, instructing it to daemonize and create a PID file: =20 --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632533; cv=none; d=zohomail.com; s=zohoarc; b=H/QiaU7qb72mpg7b39tt8lvFdc9xkR69/QSchmflBEPQHsPmKGmPIP3Ev+1Bm6Zjens2DsaRjG+ti9qv94jZf7WR/MxHymS7ShZ/xKnFd/FWwKrAhtnCruNy7zDlt99IPHMQkCVCUeOJQWrlXiGpII4cfFMrgqYrTXQyTU5wlS4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632533; 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=ckFR0Tjz1yKtns+94EL6w/3O7eMJ3f8n28lX/qrRRPs=; b=WKFpscWLL6mtLcm23M84adn6fBXwwuYtAzrRRIqtYXcsxeIxtGhvEfAvYOF7f+MAVnfWdTOitf/+b2t1quSPeAFPDbfMHCdBaf5jdGep05UfSXV0AqaoCST9ZTx2nhFIUP4qGST+umLtPjA1Tmi8MtB7BeCx0zZ1qJ5xJGl35XU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 160563253370967.88009668249163; Tue, 17 Nov 2020 09:02:13 -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-91-uGO6acCIN-KTJuqqax5nAQ-1; Tue, 17 Nov 2020 12:02:08 -0500 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0F9D1186840E; Tue, 17 Nov 2020 17:02:02 +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 D745510023A5; Tue, 17 Nov 2020 17:02:01 +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 840698C7A0; Tue, 17 Nov 2020 17:02:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAaZi027977 for ; Tue, 17 Nov 2020 11:10:36 -0500 Received: by smtp.corp.redhat.com (Postfix) id E430A5B4B0; Tue, 17 Nov 2020 16:10:36 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 464B976640; Tue, 17 Nov 2020 16:10:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632532; 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=ckFR0Tjz1yKtns+94EL6w/3O7eMJ3f8n28lX/qrRRPs=; b=PG148aHEnTr5Tn2+2dRpCN6IKhsbm4Uiuw5k9M3NbGK/x4OjnkOBDppI1BgSqA6quX9N25 8v8PqqMQz8ExhDmFua6f6TNzKv1xp4agO0iLZYqkoiQWwB6pketqTakQ+kcpwX4+pbhGxt dxy6OZzdy4ANUyyYq9I0M66M4ZbVNIk= X-MC-Unique: uGO6acCIN-KTJuqqax5nAQ-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 03/16] docs: tweak heading for daemon manual pages Date: Tue, 17 Nov 2020 16:10:14 +0000 Message-Id: <20201117161027.210543-4-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.22 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This group will be distinct from the per-driver modular daemon mapages. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 3624ae4e8f..e116c6f415 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -2,8 +2,10 @@ Libvirt Manual Pages =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -Daemons -=3D=3D=3D=3D=3D=3D=3D +Common Daemons +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +These daemons provide functionality across multiple libvirt drivers =20 * `libvirtd(8) `__ - libvirt management daemon * `virtlockd(8) `__ - libvirt lock management daemon --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632538; cv=none; d=zohomail.com; s=zohoarc; b=G3e9Ez3vhRC+HdzDWzG+gTNjgnROzBwIIjE+E/WkZCeP3e0botfEtLuR5TIQwTw+Tpuyc7STlgMbnOKjyL6orh4h/VgsqpYykSGEd/VLqyiw9sQfOjqINOGeiiG9L16Qw5riX9z35t2aFKzSYpMWrsqwVlmHS14AnUCRDlMh9Ms= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632538; 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=xfQRckvFrbV3bTD++vh6AqEmdx+hxFvNnE+8zotZnOc=; b=drFMoWtczXtE4v0ChZ9qQ73Y0h+j8SttWkdMjEU1R4uDqrF1txDaBAzoBjKGfkWeP/VlSGEjMeOxvZm9WkqY1DCpgooD42ZnW4odGnoCKMb27N8t6M2SuYfIiVJ42jUlJdJPwsHuzhHmF1scQFcO4cTaZsTZ8EQerj5He4YI1nY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632538030870.9149947743015; Tue, 17 Nov 2020 09:02:18 -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-65-f0va6SY8MqKl4rSl6W92Eg-1; Tue, 17 Nov 2020 12:02:11 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E0AF1186DD37; Tue, 17 Nov 2020 17:02:03 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BADAB5B4B6; Tue, 17 Nov 2020 17:02:03 +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 79FB6181A07B; Tue, 17 Nov 2020 17:02:03 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAc1U027988 for ; Tue, 17 Nov 2020 11:10:38 -0500 Received: by smtp.corp.redhat.com (Postfix) id 1C0E35B4BB; Tue, 17 Nov 2020 16:10:38 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4E16B5B4A2; Tue, 17 Nov 2020 16:10:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632535; 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=xfQRckvFrbV3bTD++vh6AqEmdx+hxFvNnE+8zotZnOc=; b=XzW0oB1mT+qaufaB+2p+ap7CUNBXXRwFp7x/iy8cTjBC4AIu1X0+qQANB0qT8byJtudG5B mmORfNHIDlgDU5R9/KzKvYuxX3eL0lKEguIvTBYRZq74+ULMF4PglaTkM5ZTdWMWDwrihM 2MySdMRPXP4mj++RMKeWnDdKvr6M15g= X-MC-Unique: f0va6SY8MqKl4rSl6W92Eg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 04/16] docs: add manpage for virtproxyd Date: Tue, 17 Nov 2020 16:10:15 +0000 Message-Id: <20201117161027.210543-5-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtproxyd.rst | 256 +++++++++++++++++++++++++++++++++++ 3 files changed, 258 insertions(+) create mode 100644 docs/manpages/virtproxyd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index e116c6f415..6a2a1e065d 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -10,6 +10,7 @@ These daemons provide functionality across multiple libvi= rt drivers * `libvirtd(8) `__ - libvirt management daemon * `virtlockd(8) `__ - libvirt lock management daemon * `virtlogd(8) `__ - libvirt log management daemon +* `virtproxyd(8) `__ - libvirt proxy daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index f6388b6262..7d5a81ecd5 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -24,6 +24,7 @@ docs_man_files =3D [ { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('W= ITH_SANLOCK') }, { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRT= D') }, { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, + { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtproxyd.rst b/docs/manpages/virtproxyd.rst new file mode 100644 index 0000000000..a8a0c044fa --- /dev/null +++ b/docs/manpages/virtproxyd.rst @@ -0,0 +1,256 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtproxyd +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +-------------------- +libvirt proxy daemon +-------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtproxyd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtproxyd`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts an + + * Listens on a UNIX socket to provide backwards compatibility for clients + that previously connected to the ``libvirtd`` socket. + + * Optionally listens on TCP ports for connections from off-node clients + +Upon receiving RPC messages from a client ``virtproxyd`` will transparently +forward them on to the appropriate modular daemon, and similarly relay back +any asynchronous events. + +By default, the ``virtproxyd`` daemon listens for requests on a local Unix +domain socket with the same path previously used by ``libvirtd``. The +configuration file can be used to instruct it to also listen on TCP socket= (s). +Systemd socket activation is also supported to allow it to receive pre-ope= ned +listener sockets on startup. + +Since ``virtproxyd`` merely forwards RPC mesages, it has no important stat= e, +and can be restarted at any time. Clients should expect to reconnect after +the restart. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtproxyd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. +It will also listen on TCP/IP socket(s), according to the ``listen_tcp`` +and ``listen_tls`` options in ``/etc/libvirt/virtproxyd.conf`` + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX, and optionally TCP/IP, sockets and pass them as pre-opened +file descriptors. In this mode most of the socket related config options in +``/etc/libvirt/virtproxyd.conf`` will no longer have any effect. To enable +TCP or TLS sockets use either + +:: + + $ systemctl start virtproxyd-tls.socket + +Or + +:: + + $ systemctl start virtproxyd-tcp.socket + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtproxyd.socket virtproxyd-ro.socket \ + virtproxyd-admin.socket virtproxyd-tls.socket virtproxyd-tcp.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtproxyd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtproxyd.conf`` + +The default configuration file used by ``virtproxyd``, unless overridden o= n the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/libvirt-sock`` +* ``@RUNSTATEDIR@/libvirt/libvirt-sock-ro`` + +The sockets ``virtproxyd`` will use. + +* ``@SYSCONFDIR@/pki/CA/cacert.pem`` + +The TLS **Certificate Authority** certificate ``virtproxyd`` will use. + +* ``@SYSCONFDIR@/pki/libvirt/servercert.pem`` + +The TLS **Server** certificate ``virtproxyd`` will use. + +* ``@SYSCONFDIR@/pki/libvirt/private/serverkey.pem`` + +The TLS **Server** private key ``virtproxyd`` will use. + +* ``@RUNSTATEDIR@/virtproxyd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtproxyd.conf`` + +The default configuration file used by ``virtproxyd``, unless overridden o= n the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/libvirt-sock`` + +The socket ``virtproxyd`` will use. + +* ``$HOME/.pki/libvirt/cacert.pem`` + +The TLS **Certificate Authority** certificate ``virtproxyd`` will use. + +* ``$HOME/.pki/libvirt/servercert.pem`` + +The TLS **Server** certificate ``virtproxyd`` will use. + +* ``$HOME/.pki/libvirt/serverkey.pem`` + +The TLS **Server** private key ``virtproxyd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtproxyd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtproxyd`` wil= l use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtproxyd`` wil= l use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtproxyd``: + +:: + + # virtproxyd --version + virtproxyd (libvirt) 6.6.0 + + +To start ``virtproxyd``, instructing it to daemonize and create a PID file: + +:: + + # virtproxyd -d + # ls -la @RUNSTATEDIR@/virtproxyd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtproxyd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtproxyd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632540; cv=none; d=zohomail.com; s=zohoarc; b=W5NJo3DhUKYdOwlw9aVR5LARuCHjY40pQqo9ysXNirt4Wv0JEaQxpfBHOOQfD9DlU27Ly4z0B5SQOTto4xbVN9yuURSgSkLjNfD/R/M1WGzox7SNI73k8ChzawBQ0hemqVsN1Xl451C9uKN0mN1IoNq4IeaZuLPD1tPtwOzWGvc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632540; 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=HKcHnM4eUzCPW2wPIU2NJINem1SkkBnW7NUDY+2dZbc=; b=aTkuUtzXLLBw9XpyCeL0KAk0QNE5nr0H+eJpUH/rf3Fk3K5lYKOZELM2Vrzzxzpsx3QALEmC7ywmgC/kMwqdS2jj0PSFn4/SHsM1RXiivmAAyeMg2AHew0JlkwhctfRW/b+cXNxJk+ZS58qU5ortmIV9wknOEHnAxJoCvdom7NI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632540013878.7077219826481; Tue, 17 Nov 2020 09:02:20 -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-156-B6kns3kPPhGrjoCpy6SwCQ-1; Tue, 17 Nov 2020 12:02:14 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 111EB11BD34E; Tue, 17 Nov 2020 17:02:07 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E03481759F; Tue, 17 Nov 2020 17:02:06 +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 A6B0D181A271; Tue, 17 Nov 2020 17:02:06 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAd6x027994 for ; Tue, 17 Nov 2020 11:10:39 -0500 Received: by smtp.corp.redhat.com (Postfix) id 5C7655B4A2; Tue, 17 Nov 2020 16:10:39 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 85D3D5B4BC; Tue, 17 Nov 2020 16:10:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632538; 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=HKcHnM4eUzCPW2wPIU2NJINem1SkkBnW7NUDY+2dZbc=; b=PL5J8OHwmFtS/TL5g/SEelBVEgVAAECKx0CMcx9nm9anOOUMIMZM8MaBfSMkpVPk48JncY tMpcVVRZRbey5tSeNdADURlFYCG/1DBbtVCMkGUIMIPakuQr5ktmNeItmuCNO0LC9oAD5y AtUI2CPTm7xMi12oMa1N0S88rY4Nu7M= X-MC-Unique: B6kns3kPPhGrjoCpy6SwCQ-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 05/16] docs: add manpage for virtbhyved Date: Tue, 17 Nov 2020 16:10:16 +0000 Message-Id: <20201117161027.210543-6-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 7 ++ docs/manpages/meson.build | 1 + docs/manpages/virtbhyved.rst | 215 +++++++++++++++++++++++++++++++++++ 3 files changed, 223 insertions(+) create mode 100644 docs/manpages/virtbhyved.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 6a2a1e065d..da835d62ec 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -12,6 +12,13 @@ These daemons provide functionality across multiple libv= irt drivers * `virtlogd(8) `__ - libvirt log management daemon * `virtproxyd(8) `__ - libvirt proxy daemon =20 +Modular Driver daemons +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +These daemons provide functionality to a single libvirt driver + +* `virtbhyved(8) `__ - libvirt bhyve management daemon + Tools =3D=3D=3D=3D=3D =20 diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 7d5a81ecd5..7c03cb74cf 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -22,6 +22,7 @@ docs_man_files =3D [ =20 { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('W= ITH_SANLOCK') }, + { 'name': 'virtbhyved', 'section': '8', 'install': conf.has('WITH_BHYVE'= ) }, { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRT= D') }, { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, diff --git a/docs/manpages/virtbhyved.rst b/docs/manpages/virtbhyved.rst new file mode 100644 index 0000000000..4d1d36b161 --- /dev/null +++ b/docs/manpages/virtbhyved.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtbhyved +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------- +libvirt bhyve management daemon +------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtbhyved`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtbhyved`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for bhyve v= irtual +machines. + +The ``virtbhyved`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtbhyved`` does not interrupt running guests. Guests contin= ue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtbhyved`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtbhyved.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtbhyved.socket virtbhyved-ro.socket \ + virtbhyved-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtbhyved`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtbhyved.conf`` + +The default configuration file used by ``virtbhyved``, unless overridden o= n the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtbhyved-sock`` +* ``@RUNSTATEDIR@/libvirt/virtbhyved-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtbhyved-admin-sock`` + +The sockets ``virtbhyved`` will use. + +The TLS **Server** private key ``virtbhyved`` will use. + +* ``@RUNSTATEDIR@/virtbhyved.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtbhyved.conf`` + +The default configuration file used by ``virtbhyved``, unless overridden o= n the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtbhyved-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtbhyved-admin-sock`` + +The sockets ``virtbhyved`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtbhyved.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtbhyved`` wil= l use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtbhyved`` wil= l use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtbhyved``: + +:: + + # virtbhyved --version + virtbhyved (libvirt) @VERSION@ + + +To start ``virtbhyved``, instructing it to daemonize and create a PID file: + +:: + + # virtbhyved -d + # ls -la @RUNSTATEDIR@/virtbhyved.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtbhyved.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtbhyved`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvbhyve.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632545; cv=none; d=zohomail.com; s=zohoarc; b=ZlKCCUA6OdnbotLYEhxOFGNBCo/1ETbES1GzHx7DqOwMtRLCAp5rrznuq2xNlGi7lHQQUxDwBR6U+t698hUmkZnOMEPIRD3gdJGigFA4GszTeWNc48KtnyUV5FbS/or1pT0Becnlt6WFy78sOj5eDGdpN7ZsUzqNG7XsqYBkHCc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632545; 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=EPutSsfPprA5oZ+DimfeW8LGUbDyIx7SsnUZ8vndiNc=; b=UsoCNxuTLju7onbzzxqnYugf10gMwF7HW3ayyftaXPw+ZXj7kr0F14eLm04AAugTCk/JT7km+CH/eS/nOY3dD3DnZ7CucSSQTarHsWtmgsl9pjeD91UEVnymL/wJ38IPy079GhEoZfex8aXijlK6RnpEUytM8ki2Z1cEbP2FLks= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632545392565.6492271413023; Tue, 17 Nov 2020 09:02:25 -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-409-7Q5aRHyOPECY4Z7huJD0Mg-1; Tue, 17 Nov 2020 12:02:20 -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 D33CE100855F; Tue, 17 Nov 2020 17:02:09 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id ABB38196FB; Tue, 17 Nov 2020 17:02:09 +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 458B2181A71E; Tue, 17 Nov 2020 17:02:09 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAeTW027999 for ; Tue, 17 Nov 2020 11:10:40 -0500 Received: by smtp.corp.redhat.com (Postfix) id 7A3055B4A2; Tue, 17 Nov 2020 16:10:40 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id B20A35B4B0; Tue, 17 Nov 2020 16:10:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632544; 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=EPutSsfPprA5oZ+DimfeW8LGUbDyIx7SsnUZ8vndiNc=; b=WJF5j7YxuwYct3C6Un9hWNf2Y5jYbCZ+/PLZJGysKHNDitwSOU1VC/D6c/AKvomEzbYJEK bTndr4FhUYNzxFBLeUojHHz3KD34P3vDJ4JKSkopUpIHKo7T+m9/r0nkEtmCiH2t9JJFRT R6jQFQo4kWq+Lv7UcbUVGFJpmk1UmUI= X-MC-Unique: 7Q5aRHyOPECY4Z7huJD0Mg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 06/16] docs: add manpage for virtinterfaced Date: Tue, 17 Nov 2020 16:10:17 +0000 Message-Id: <20201117161027.210543-7-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtinterfaced.rst | 215 +++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtinterfaced.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index da835d62ec..18153ac714 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -18,6 +18,7 @@ Modular Driver daemons These daemons provide functionality to a single libvirt driver =20 * `virtbhyved(8) `__ - libvirt bhyve management daemon +* `virtinterfaced(8) `__ - libvirt host network inter= face management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 7c03cb74cf..a46f75d503 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -23,6 +23,7 @@ docs_man_files =3D [ { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('W= ITH_SANLOCK') }, { 'name': 'virtbhyved', 'section': '8', 'install': conf.has('WITH_BHYVE'= ) }, + { 'name': 'virtinterfaced', 'section': '8', 'install': conf.has('WITH_IN= TERFACE') }, { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRT= D') }, { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, diff --git a/docs/manpages/virtinterfaced.rst b/docs/manpages/virtinterface= d.rst new file mode 100644 index 0000000000..5777dba638 --- /dev/null +++ b/docs/manpages/virtinterfaced.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtinterfaced +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------------------------ +libvirt host network interface management daemon +------------------------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtinterfaced`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtinterfaced`` program is a server side daemon component of the li= bvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for host ne= twork +interfaces. + +The ``virtinterfaced`` daemon only listens for requests on a local Unix do= main +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtinterfaced`` does not interrupt running guests. Guests co= ntinue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtinterfaced`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtinterfaced.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtinterfaced.socket virtinterfaced-ro.socket \ + virtinterfaced-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtinterfaced`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtinterfaced.conf`` + +The default configuration file used by ``virtinterfaced``, unless overridd= en on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtinterfaced-sock`` +* ``@RUNSTATEDIR@/libvirt/virtinterfaced-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtinterfaced-admin-sock`` + +The sockets ``virtinterfaced`` will use. + +The TLS **Server** private key ``virtinterfaced`` will use. + +* ``@RUNSTATEDIR@/virtinterfaced.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtinterfaced.conf`` + +The default configuration file used by ``virtinterfaced``, unless overridd= en on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtinterfaced-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtinterfaced-admin-sock`` + +The sockets ``virtinterfaced`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtinterfaced.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtinterfaced``= will use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtinterfaced``= will use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtinterfaced``: + +:: + + # virtinterfaced --version + virtinterfaced (libvirt) @VERSION@ + + +To start ``virtinterfaced``, instructing it to daemonize and create a PID = file: + +:: + + # virtinterfaced -d + # ls -la @RUNSTATEDIR@/virtinterfaced.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtinterfaced.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtinterfaced`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvinterface.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632582; cv=none; d=zohomail.com; s=zohoarc; b=BdS5O9JsYBGQqzFbq3rA4s9LoG66GpJelLBYLjpujnV0ibmvTjgvxND4pglH4+Ro/EnfE90QZz0qjRJQSRv8fB7kAYw+nDTmrw94yOhHOotv5iV5fZv/MVCH/bl0x/GJ9DLQ5F7m9xxDnXXcDIQgqcvyud67l3wHBieQTWig10I= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632582; 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=qXxVRx3H5yRv3l2ny0qDdqbbkUMB6my5n1BgqnEIOoU=; b=dONYCcdtKkD3LZnqDgCsen2pmWw0JDJ2+0ygxJDixsBATMTOpHBnLMzg0dgk3d/ubq8oSpP2Hy3AmbdBaJ+BtleXXOsvX5db1gprvy5f2m0OZr8NAAy034RS/yKHIwPBsJzymC6i815BQtUu+xrgjiySu9H36jOk/8M+HUx3CTU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 16056325826491000.3659822203773; Tue, 17 Nov 2020 09:03:02 -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-314-KgZ9xZJJMg6vR5CPeSw0zw-1; Tue, 17 Nov 2020 12:02:53 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 660E51882FAA; Tue, 17 Nov 2020 17:02:46 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0B5C855765; Tue, 17 Nov 2020 17:02:46 +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 C3A4E1832FE5; Tue, 17 Nov 2020 17:02:45 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAfOf028005 for ; Tue, 17 Nov 2020 11:10:41 -0500 Received: by smtp.corp.redhat.com (Postfix) id 8F12F5B4A2; Tue, 17 Nov 2020 16:10:41 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id D29BB5B4BC; Tue, 17 Nov 2020 16:10:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632576; 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=qXxVRx3H5yRv3l2ny0qDdqbbkUMB6my5n1BgqnEIOoU=; b=SQnFG+CX2WhhmzTUZgFJQ3fN2iKX7BwQOgmqbpJWCNGmqp3aeqa9OlP2uaIE3CCiCwV7Yq HlF32eTHc2RCF+7AmnuxoTCj7k5YwTQZmZa9uxjcjJioXKVeucTownxC+SPaxfMc68eFnE PEpW/EaqD8mWrXJ3Q0httecaeO6z/o0= X-MC-Unique: KgZ9xZJJMg6vR5CPeSw0zw-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 07/16] docs: add manpage for virtlxcd Date: Tue, 17 Nov 2020 16:10:18 +0000 Message-Id: <20201117161027.210543-8-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtlxcd.rst | 215 +++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtlxcd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 18153ac714..0eab1056e4 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -19,6 +19,7 @@ These daemons provide functionality to a single libvirt d= river =20 * `virtbhyved(8) `__ - libvirt bhyve management daemon * `virtinterfaced(8) `__ - libvirt host network inter= face management daemon +* `virtlxcd(8) `__ - libvirt LXC management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index a46f75d503..083289642a 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -26,6 +26,7 @@ docs_man_files =3D [ { 'name': 'virtinterfaced', 'section': '8', 'install': conf.has('WITH_IN= TERFACE') }, { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRT= D') }, { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, + { 'name': 'virtlxcd', 'section': '8', 'install': conf.has('WITH_LXC') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, ] =20 diff --git a/docs/manpages/virtlxcd.rst b/docs/manpages/virtlxcd.rst new file mode 100644 index 0000000000..f89d70ba21 --- /dev/null +++ b/docs/manpages/virtlxcd.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D +virtlxcd +=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------ +libvirt LXC management daemon +------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtlxcd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtlxcd`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for LXC +containers. + +The ``virtlxcd`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtlxcd`` does not interrupt running guests. Guests continue= to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtlxcd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtlxcd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtlxcd.socket virtlxcd-ro.socket \ + virtlxcd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtlxcd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtlxcd.conf`` + +The default configuration file used by ``virtlxcd``, unless overridden on = the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtlxcd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtlxcd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtlxcd-admin-sock`` + +The sockets ``virtlxcd`` will use. + +The TLS **Server** private key ``virtlxcd`` will use. + +* ``@RUNSTATEDIR@/virtlxcd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtlxcd.conf`` + +The default configuration file used by ``virtlxcd``, unless overridden on = the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlxcd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtlxcd-admin-sock`` + +The sockets ``virtlxcd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlxcd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtlxcd`` will = use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtlxcd`` will = use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtlxcd``: + +:: + + # virtlxcd --version + virtlxcd (libvirt) @VERSION@ + + +To start ``virtlxcd``, instructing it to daemonize and create a PID file: + +:: + + # virtlxcd -d + # ls -la @RUNSTATEDIR@/virtlxcd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtlxcd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtlxcd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvlxc.html = `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632657; cv=none; d=zohomail.com; s=zohoarc; b=NA9D+gjNzw9ETzLO0+LpEUjwHhwcIq7zCwwkAXfhBAuHcI4ElZGg4RzZ3kMmncbSehR8Ip6kP+7BmR5w0s+SIfb1T3yMQ56hK/Nv2h4EB99gRZ8fPHakZq66p5Cc/Qsz494cLQLp5QxVDOOslXVy9mmlMcqMugWpGtORFw24TJA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632657; 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=qr5bo5YLlS0JVEyWFzDtIZk99J9/WYRUHHT7udCYBgA=; b=lg1pX2JkLq0Srxv+L70ggxzmGMo/5yYywa6Ccq9cYRRNDCDB0kTPkauKq5H8bvB/4oo4Ho6eFk1EcBsMBYPypsHy6nVBdafqXj1o8om62sShv1DQN599TbaiYtVVeruMnuNbXuS43rD+GJvIr4+Sh/S8gL3uD+HpTgtlHf3IZ9Q= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632657510917.7444822471538; Tue, 17 Nov 2020 09:04:17 -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-449-MhM_UY12P4KBX80KGb5kAA-1; Tue, 17 Nov 2020 12:02:26 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id B1F91873119; Tue, 17 Nov 2020 17:02:13 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 838375C1CF; Tue, 17 Nov 2020 17:02:13 +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 44E52181A872; Tue, 17 Nov 2020 17:02:13 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAgvA028014 for ; Tue, 17 Nov 2020 11:10:42 -0500 Received: by smtp.corp.redhat.com (Postfix) id A63D55B4A2; Tue, 17 Nov 2020 16:10:42 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id EA2575B4BC; Tue, 17 Nov 2020 16:10:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632656; 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=qr5bo5YLlS0JVEyWFzDtIZk99J9/WYRUHHT7udCYBgA=; b=U9+pI6lxFQSxqzLHFewvE0WMQZkp046ZQQLDG093lIhIQdJgF7kr++ofYppLkmXx6P/tvh TNlUcBtcWzOHw8XdDM6qPNjqs2XY82v+GTauA23bmReOlhc5PQMxLss8K6QdDgLoNcK7ER hUfgFwvhPs+jXOiFgVCUamxeb+A3cyk= X-MC-Unique: MhM_UY12P4KBX80KGb5kAA-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 08/16] docs: add manpage for virtnetworkd Date: Tue, 17 Nov 2020 16:10:19 +0000 Message-Id: <20201117161027.210543-9-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtnetworkd.rst | 215 +++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtnetworkd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 0eab1056e4..2ce222f952 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -20,6 +20,7 @@ These daemons provide functionality to a single libvirt d= river * `virtbhyved(8) `__ - libvirt bhyve management daemon * `virtinterfaced(8) `__ - libvirt host network inter= face management daemon * `virtlxcd(8) `__ - libvirt LXC management daemon +* `virtnetworkd(8) `__ - libvirt virtual network manage= ment daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 083289642a..4c294909ee 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -27,6 +27,7 @@ docs_man_files =3D [ { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRT= D') }, { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virtlxcd', 'section': '8', 'install': conf.has('WITH_LXC') }, + { 'name': 'virtnetworkd', 'section': '8', 'install': conf.has('WITH_NETW= ORK') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, ] =20 diff --git a/docs/manpages/virtnetworkd.rst b/docs/manpages/virtnetworkd.rst new file mode 100644 index 0000000000..1ef9a12210 --- /dev/null +++ b/docs/manpages/virtnetworkd.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtnetworkd +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +----------------------------------------- +libvirt virtual network management daemon +----------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtnetworkd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnetworkd`` program is a server side daemon component of the libv= irt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for virtual +networks. + +The ``virtnetworkd`` daemon only listens for requests on a local Unix doma= in +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtnetworkd`` does not interrupt running guests. Guests cont= inue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnetworkd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtnetworkd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtnetworkd.socket virtnetworkd-ro.socket \ + virtnetworkd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtnetworkd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtnetworkd.conf`` + +The default configuration file used by ``virtnetworkd``, unless overridden= on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtnetworkd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtnetworkd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtnetworkd-admin-sock`` + +The sockets ``virtnetworkd`` will use. + +The TLS **Server** private key ``virtnetworkd`` will use. + +* ``@RUNSTATEDIR@/virtnetworkd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtnetworkd.conf`` + +The default configuration file used by ``virtnetworkd``, unless overridden= on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnetworkd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtnetworkd-admin-sock`` + +The sockets ``virtnetworkd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnetworkd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtnetworkd`` w= ill use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtnetworkd`` w= ill use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtnetworkd``: + +:: + + # virtnetworkd --version + virtnetworkd (libvirt) @ + + +To start ``virtnetworkd``, instructing it to daemonize and create a PID fi= le: + +:: + + # virtnetworkd -d + # ls -la @RUNSTATEDIR@/virtnetworkd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtnetworkd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtnetworkd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvnetwork.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632551; cv=none; d=zohomail.com; s=zohoarc; b=XZjMaX322HOOs8bGONZgESweSpYDL0c50VDjJRZWwDbOHOem6RH6SkVulEGkboxrXbYnynObpYJjTtfyYKjSQZYTgIoSeByWVZh+jRi7mRj3wLRt7TPY0BTMOIslkvsoCmvIHMEJ+YnCknP6QyAprAdCVS7xohgJbHiT8O2ZNRg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632551; 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=4tjDIhsZfPTrCwmgGZrsT8/qj7/gWorCuoCAIfPIzew=; b=K2Tgm3TJoe3OKtS2AuKw+bsENzdxG/yJ0qnwrSpNo1uDj2U3Os9L6sYLUx3Gm7u57Pzh7Hy0X22iz9DAFt3x+axQk+QemSuYFv8WV5XjbHZ64XqvahPhrgNcqY8FAgGGCDhZ/CR/xi8l4cv+dUqkv+p6A8ZPBqJZhgM2L20Nv2A= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632550487180.09032875639707; Tue, 17 Nov 2020 09:02:30 -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-228-BfGjE6hNMbq4Uy420qnIhA-1; Tue, 17 Nov 2020 12:02:24 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id B5B778042D3; Tue, 17 Nov 2020 17:02:16 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 908B05C1CF; Tue, 17 Nov 2020 17:02:16 +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 52F3E18095FF; Tue, 17 Nov 2020 17:02:16 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAh4I028025 for ; Tue, 17 Nov 2020 11:10:43 -0500 Received: by smtp.corp.redhat.com (Postfix) id DF83F5B4A2; Tue, 17 Nov 2020 16:10:43 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1EC5676644; Tue, 17 Nov 2020 16:10:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632547; 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=4tjDIhsZfPTrCwmgGZrsT8/qj7/gWorCuoCAIfPIzew=; b=iMtgX5EGA5bh5iqnWKKb6xCvX+l+QhSVl57HAVAXHxMCIJjN/AeRtcvkGY1yMPZ6JW1uay TXi3c1Z0wNq0D/aPeGVaNNw6K04iGPVzCS41WtaspHbWvdwHRgPEd3Ia0WfTG7XujR1Ucm Q2n9WpZyQCYL+uYzDc+0w+v2dkU4qdU= X-MC-Unique: BfGjE6hNMbq4Uy420qnIhA-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 09/16] docs: add manpage for virtnodedevd Date: Tue, 17 Nov 2020 16:10:20 +0000 Message-Id: <20201117161027.210543-10-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtnodedevd.rst | 214 +++++++++++++++++++++++++++++++++ 3 files changed, 216 insertions(+) create mode 100644 docs/manpages/virtnodedevd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 2ce222f952..5e87870f4b 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -21,6 +21,7 @@ These daemons provide functionality to a single libvirt d= river * `virtinterfaced(8) `__ - libvirt host network inter= face management daemon * `virtlxcd(8) `__ - libvirt LXC management daemon * `virtnetworkd(8) `__ - libvirt virtual network manage= ment daemon +* `virtnodedevd(8) `__ - libvirt host device management= daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 4c294909ee..85f45410a0 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -28,6 +28,7 @@ docs_man_files =3D [ { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD= ') }, { 'name': 'virtlxcd', 'section': '8', 'install': conf.has('WITH_LXC') }, { 'name': 'virtnetworkd', 'section': '8', 'install': conf.has('WITH_NETW= ORK') }, + { 'name': 'virtnodedevd', 'section': '8', 'install': conf.has('WITH_NODE= _DEVICES') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, ] =20 diff --git a/docs/manpages/virtnodedevd.rst b/docs/manpages/virtnodedevd.rst new file mode 100644 index 0000000000..a29c0dbc9e --- /dev/null +++ b/docs/manpages/virtnodedevd.rst @@ -0,0 +1,214 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtnodedevd +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------------- +libvirt host device management daemon +------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtnodedevd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnodedevd`` program is a server side daemon component of the libv= irt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for host de= vices. + +The ``virtnodedevd`` daemon only listens for requests on a local Unix doma= in +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtnodedevd`` does not interrupt running guests. Guests cont= inue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnodedevd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtnodedevd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtnodedevd.socket virtnodedevd-ro.socket \ + virtnodedevd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtnodedevd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtnodedevd.conf`` + +The default configuration file used by ``virtnodedevd``, unless overridden= on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtnodedevd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtnodedevd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtnodedevd-admin-sock`` + +The sockets ``virtnodedevd`` will use. + +The TLS **Server** private key ``virtnodedevd`` will use. + +* ``@RUNSTATEDIR@/virtnodedevd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtnodedevd.conf`` + +The default configuration file used by ``virtnodedevd``, unless overridden= on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnodedevd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtnodedevd-admin-sock`` + +The sockets ``virtnodedevd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnodedevd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtnodedevd`` w= ill use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtnodedevd`` w= ill use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtnodedevd``: + +:: + + # virtnodedevd --version + virtnodedevd (libvirt) @ + + +To start ``virtnodedevd``, instructing it to daemonize and create a PID fi= le: + +:: + + # virtnodedevd -d + # ls -la @RUNSTATEDIR@/virtnodedevd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtnodedevd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtnodedevd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvnodedev.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632540; cv=none; d=zohomail.com; s=zohoarc; b=Na/zrvFZiwAI79iivVxA64j8o00xnSHnRM30I6jGy14gTRnUCAJ4+vbPTyX/RDIo2Yw/O4ORKV85SwxQyMPPJ6uo0ykH+o7kn9tlL8SKuzyuFZgzEWyTcMBJn5tkJh5zAlDYRDSIQLF9j6cnjkU74v3EWRv6i2SgTJEhlBIO4C0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632540; 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=ZHYj46yA4Tr7F+Sn7l2QgG/4JwuK5LgzUHTNpXtNWMo=; b=ZvjMXBwXDCYC7nsxRlyX1/0JxSbsYLADayxlse3ru4CMXTrPohxZ442Uq4yowkhgGajrIFzVlYaBjKyYwxREMB0h8Ad8Ce01Bw4tBCudCgtbBlRgJU05hDSx56h3+m9xgY1LuQk2kkfZ8LtUTiKq8M8yY6ICdnleoLztLRB81ec= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 160563254046588.80825215391542; Tue, 17 Nov 2020 09:02:20 -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-463-YK-bVcNcOyqTmswbDk5ePw-1; Tue, 17 Nov 2020 12:02:13 -0500 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id EA377186DD27; Tue, 17 Nov 2020 17:02:06 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C7AF95D9EF; Tue, 17 Nov 2020 17:02:06 +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 8BCBB181A270; Tue, 17 Nov 2020 17:02:06 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAjIU028032 for ; Tue, 17 Nov 2020 11:10:45 -0500 Received: by smtp.corp.redhat.com (Postfix) id 031925B4B6; Tue, 17 Nov 2020 16:10:45 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5497E5B4A2; Tue, 17 Nov 2020 16:10:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632539; 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=ZHYj46yA4Tr7F+Sn7l2QgG/4JwuK5LgzUHTNpXtNWMo=; b=OQj7OSzVg/tO5rdhe7O0fqDVEOMOjeXDxzmrNphtMkhfHMWZ80muimLSFlj5015gh3Lnmh t5biVEev5mlK9rKVxkV4Ncscdl/Uu0xjHnIbzyrY3qCuvyHSkRPss8C32TWAjK4tVzf4rq l9vR67qKi0CmGalUO635mUSu/ar+1nU= X-MC-Unique: YK-bVcNcOyqTmswbDk5ePw-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 10/16] docs: add manpage for virtnwfilterd Date: Tue, 17 Nov 2020 16:10:21 +0000 Message-Id: <20201117161027.210543-11-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtnwfilterd.rst | 215 ++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtnwfilterd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 5e87870f4b..e70b560a0d 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -22,6 +22,7 @@ These daemons provide functionality to a single libvirt d= river * `virtlxcd(8) `__ - libvirt LXC management daemon * `virtnetworkd(8) `__ - libvirt virtual network manage= ment daemon * `virtnodedevd(8) `__ - libvirt host device management= daemon +* `virtnwfilterd(8) `__ - libvirt network filter manag= ement daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 85f45410a0..019accbca2 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -29,6 +29,7 @@ docs_man_files =3D [ { 'name': 'virtlxcd', 'section': '8', 'install': conf.has('WITH_LXC') }, { 'name': 'virtnetworkd', 'section': '8', 'install': conf.has('WITH_NETW= ORK') }, { 'name': 'virtnodedevd', 'section': '8', 'install': conf.has('WITH_NODE= _DEVICES') }, + { 'name': 'virtnwfilterd', 'section': '8', 'install': conf.has('WITH_NWF= ILTER') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, ] =20 diff --git a/docs/manpages/virtnwfilterd.rst b/docs/manpages/virtnwfilterd.= rst new file mode 100644 index 0000000000..47cca7e282 --- /dev/null +++ b/docs/manpages/virtnwfilterd.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtnwfilterd +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +---------------------------------------- +libvirt network filter management daemon +---------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtnwfilterd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnwfilterd`` program is a server side daemon component of the lib= virt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for network +filters. + +The ``virtnwfilterd`` daemon only listens for requests on a local Unix dom= ain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtnwfilterd`` does not interrupt running guests. Guests con= tinue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtnwfilterd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtnwfilterd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtnwfilterd.socket virtnwfilterd-ro.socket \ + virtnwfilterd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtnwfilterd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtnwfilterd.conf`` + +The default configuration file used by ``virtnwfilterd``, unless overridde= n on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtnwfilterd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtnwfilterd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtnwfilterd-admin-sock`` + +The sockets ``virtnwfilterd`` will use. + +The TLS **Server** private key ``virtnwfilterd`` will use. + +* ``@RUNSTATEDIR@/virtnwfilterd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtnwfilterd.conf`` + +The default configuration file used by ``virtnwfilterd``, unless overridde= n on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnwfilterd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtnwfilterd-admin-sock`` + +The sockets ``virtnwfilterd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtnwfilterd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtnwfilterd`` = will use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtnwfilterd`` = will use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtnwfilterd``: + +:: + + # virtnwfilterd --version + virtnwfilterd (libvirt) @ + + +To start ``virtnwfilterd``, instructing it to daemonize and create a PID f= ile: + +:: + + # virtnwfilterd -d + # ls -la @RUNSTATEDIR@/virtnwfilterd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtnwfilterd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtnwfilterd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvnwfilter.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632574; cv=none; d=zohomail.com; s=zohoarc; b=A755SJlZUw79069p1lMZC07ync/DsJrEi/xMfnFiVoThGRjwM2p61ZjbFnU3nw05ARNv3yES2z++GwJaBiGZ1agtecJO5uM+jTYcuH8bTudToNkSDFsIqAEZj+Av/vj5KtGvtEiq8UdY3E1w6bMNNjR5sI1yN2gISUpW0YtkCCo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632574; 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=onqHmMQTOHisy77cklLy3mP9pIyBhWBTHSi684Vj4oQ=; b=jSqXJMRopmp4JuF116RkdGqSZFFqfzfkMnX6jNCtAqHmW7/Ii7kir2ck02xIJTvrU/o1Dy+Z5qaZlP6k94Vpctxb8SGYF7YDMrShtzoC4zyUDlDQikcAKGajoR9ZDjm02FhmTZmkrmeQPSAjfE0AYRCefAFwvgXttTw42BmazEw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632574174343.5084531594273; Tue, 17 Nov 2020 09:02:54 -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-372-clPLeWb8PCmkziQU9QzPGg-1; Tue, 17 Nov 2020 12:02:25 -0500 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8651C6D24A; Tue, 17 Nov 2020 17:02:19 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3A70C6EF44; Tue, 17 Nov 2020 17:02:19 +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 0312C1826D36; Tue, 17 Nov 2020 17:02:19 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAkkp028037 for ; Tue, 17 Nov 2020 11:10:46 -0500 Received: by smtp.corp.redhat.com (Postfix) id 345975B4B6; Tue, 17 Nov 2020 16:10:46 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6442A5B4A2; Tue, 17 Nov 2020 16:10:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632549; 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=onqHmMQTOHisy77cklLy3mP9pIyBhWBTHSi684Vj4oQ=; b=AJzqXnuzct9oJRVnLIaA68KqR+pINTfTuM8AWduuiiBGKhE93yZdq02oMqOJEUqrgsmm63 Wfv78qTDSh/dRFl1wvLm5EcfI30OeLYUjrkdtjLTBB3Rgvjq9R0JaL/SNKNz95pt13JdDO PbFYS/NwbK9Fx6XTkkzYevlA08wearc= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632572; 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=onqHmMQTOHisy77cklLy3mP9pIyBhWBTHSi684Vj4oQ=; b=h2Y89iwaoE+o8G+mlEaL/CGhCwsrPSMbKq/VxwK0If6v5FYsuGhhTe5AYozGtREXw8kN8V HKRlqTXHxW+/BV5sn2qyVuQ/tRDk4Pu6n4JYMho/WA/263M36kUvnzM71MzHmCYZe/x/Q5 NG98lipvuIBFk7CJmNkTXxmoVIIQdHc= X-MC-Unique: clPLeWb8PCmkziQU9QzPGg-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 11/16] docs: add manpage for virtqemud Date: Tue, 17 Nov 2020 16:10:22 +0000 Message-Id: <20201117161027.210543-12-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtqemud.rst | 215 ++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtqemud.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index e70b560a0d..67357419eb 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -23,6 +23,7 @@ These daemons provide functionality to a single libvirt d= river * `virtnetworkd(8) `__ - libvirt virtual network manage= ment daemon * `virtnodedevd(8) `__ - libvirt host device management= daemon * `virtnwfilterd(8) `__ - libvirt network filter manag= ement daemon +* `virtqemud(8) `__ - libvirt QEMU management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 019accbca2..e08365b780 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -31,6 +31,7 @@ docs_man_files =3D [ { 'name': 'virtnodedevd', 'section': '8', 'install': conf.has('WITH_NODE= _DEVICES') }, { 'name': 'virtnwfilterd', 'section': '8', 'install': conf.has('WITH_NWF= ILTER') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, + { 'name': 'virtqemud', 'section': '8', 'install': conf.has('WITH_QEMU') = }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtqemud.rst b/docs/manpages/virtqemud.rst new file mode 100644 index 0000000000..78a032caa1 --- /dev/null +++ b/docs/manpages/virtqemud.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtqemud +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------ +libvirt QEMU management daemon +------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtqemud`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtqemud`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for QEMU vi= rtual +machines. + +The ``virtqemud`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtqemud`` does not interrupt running guests. Guests continu= e to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtqemud`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtqemud.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtqemud.socket virtqemud-ro.socket \ + virtqemud-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtqemud`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtqemud.conf`` + +The default configuration file used by ``virtqemud``, unless overridden on= the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtqemud-sock`` +* ``@RUNSTATEDIR@/libvirt/virtqemud-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtqemud-admin-sock`` + +The sockets ``virtqemud`` will use. + +The TLS **Server** private key ``virtqemud`` will use. + +* ``@RUNSTATEDIR@/virtqemud.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtqemud.conf`` + +The default configuration file used by ``virtqemud``, unless overridden on= the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtqemud-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtqemud-admin-sock`` + +The sockets ``virtqemud`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtqemud.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtqemud`` will= use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtqemud`` will= use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtqemud``: + +:: + + # virtqemud --version + virtqemud (libvirt) 0.8.2 + + +To start ``virtqemud``, instructing it to daemonize and create a PID file: + +:: + + # virtqemud -d + # ls -la @RUNSTATEDIR@/virtqemud.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtqemud.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtqemud`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvqemu.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632589; cv=none; d=zohomail.com; s=zohoarc; b=JAluwuoIpeEy/nuk9ZpnW0xwb88n6NL4zTViQtYsmaVa8IuuGAB7P1piVOWQKWU7GmnVqVtB42zrwIy148M9sRX1gk4WXF6AE4H3MNdIFlnG+ATeB1M+ncS3zR8Jm4JWyMCKOjNef+Gg1rkxXspyGooTpGAleE2zOENlK/DtfDM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632589; 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=6Vu9xiGTHH3BTO9sLFQytCpJ53NGgJ9Rs0ziJ/b7pZQ=; b=Psjif00P/Kn/P6XgI+g7jrZweH4aSy8l9wSSc7OBFQSbUB1f5EgNmbyN60N0OE7ZL46Ma1EEGfuuSZWSfHpJ8j7r2/w0dyvushGqI2JMQASDzZO89N4ipd2nHAUtZtVl/lrWAvmFQQpzH2+yW/jQbFXCmcl16MbZvARmvz7tm60= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632589378499.3926306376819; Tue, 17 Nov 2020 09:03: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-U-hh2FCTPFyCBG979Y7Udw-1; Tue, 17 Nov 2020 12:02:29 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 837D76D255; Tue, 17 Nov 2020 17:02:22 +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 619915B4B6; Tue, 17 Nov 2020 17:02:22 +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 29B748C7A1; Tue, 17 Nov 2020 17:02:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAl0q028044 for ; Tue, 17 Nov 2020 11:10:47 -0500 Received: by smtp.corp.redhat.com (Postfix) id 58BCF5B4B0; Tue, 17 Nov 2020 16:10:47 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9BE505B4A2; Tue, 17 Nov 2020 16:10:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632584; 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=6Vu9xiGTHH3BTO9sLFQytCpJ53NGgJ9Rs0ziJ/b7pZQ=; b=AiBObzAO8beCyY+JeQLRvz6T2c3OFJz4tYqFttU3OeIX1PEPF7OHsNPEfijZuK/O6FmQIX nerIbwC5FgJDi3UKMZABA8GDE10tUDIk1yqRp0R8s6UG/x8Lel7dVoyzdRV8PXTGuGV5J+ gCOMmc1dRC4CmmInWbQsnVaqqJjWwLg= X-MC-Unique: U-hh2FCTPFyCBG979Y7Udw-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 12/16] docs: add manpage for virtsecretd Date: Tue, 17 Nov 2020 16:10:23 +0000 Message-Id: <20201117161027.210543-13-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtsecretd.rst | 214 ++++++++++++++++++++++++++++++++++ 3 files changed, 216 insertions(+) create mode 100644 docs/manpages/virtsecretd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 67357419eb..fb62dc86a2 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -24,6 +24,7 @@ These daemons provide functionality to a single libvirt d= river * `virtnodedevd(8) `__ - libvirt host device management= daemon * `virtnwfilterd(8) `__ - libvirt network filter manag= ement daemon * `virtqemud(8) `__ - libvirt QEMU management daemon +* `virtsecretd(8) `__ - libvirt secret data management d= aemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index e08365b780..1476722bde 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -32,6 +32,7 @@ docs_man_files =3D [ { 'name': 'virtnwfilterd', 'section': '8', 'install': conf.has('WITH_NWF= ILTER') }, { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, { 'name': 'virtqemud', 'section': '8', 'install': conf.has('WITH_QEMU') = }, + { 'name': 'virtsecretd', 'section': '8', 'install': conf.has('WITH_SECRE= TS') }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtsecretd.rst b/docs/manpages/virtsecretd.rst new file mode 100644 index 0000000000..2fa01ef147 --- /dev/null +++ b/docs/manpages/virtsecretd.rst @@ -0,0 +1,214 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtsecretd +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------------- +libvirt secret data management daemon +------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtsecretd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtsecretd`` program is a server side daemon component of the libvi= rt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for secret = data. + +The ``virtsecretd`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtsecretd`` does not interrupt running guests. Guests conti= nue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtsecretd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtsecretd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtsecretd.socket virtsecretd-ro.socket \ + virtsecretd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtsecretd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtsecretd.conf`` + +The default configuration file used by ``virtsecretd``, unless overridden = on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtsecretd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtsecretd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtsecretd-admin-sock`` + +The sockets ``virtsecretd`` will use. + +The TLS **Server** private key ``virtsecretd`` will use. + +* ``@RUNSTATEDIR@/virtsecretd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtsecretd.conf`` + +The default configuration file used by ``virtsecretd``, unless overridden = on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtsecretd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtsecretd-admin-sock`` + +The sockets ``virtsecretd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtsecretd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtsecretd`` wi= ll use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtsecretd`` wi= ll use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtsecretd``: + +:: + + # virtsecretd --version + virtsecretd (libvirt) @ + + +To start ``virtsecretd``, instructing it to daemonize and create a PID fil= e: + +:: + + # virtsecretd -d + # ls -la @RUNSTATEDIR@/virtsecretd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtsecretd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtsecretd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvsecret.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632668; cv=none; d=zohomail.com; s=zohoarc; b=J1bypdR5TAFk8cIh3B3h4hGyOPN9KRNO4/i3qLZsjzWNQLHI7rORnJ0heiJNJU2PIV1bU2MRFoxBi8DNAzt09WafJwQjHuunGjEBtPIttPogpvS4epsafPwdpBHcKaIMqlwqRB1UEDLoI6Tm76LQ8rZpNoI1G1P65N9/m4U2k0k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632668; 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=qylXKAqIG+kTbl3luWwwgNJqzV2SXcNgSvSXEqGE9+A=; b=BXA7oKzIpETxqXYF9oxPMJBKRfrJsagsCmX71KEemDa486OsHD4XJGjO7pxAyazmIWl/RWI8ZrWTNNS5qfC1lGtodzleKLLhNqc/2KEJAmyugyDA8JUwHJDNGXSYrNwDFDU4W0mOV9IWqfte+43jPApmP8WYXD1r8F2tCOXjDb8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632668328976.1682572584497; Tue, 17 Nov 2020 09:04:28 -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-203-rLPqci54NZOn2NRIdDx89g-1; Tue, 17 Nov 2020 12:02:58 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0D5681882FB6; Tue, 17 Nov 2020 17:02:49 +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 E0EAA5B4AA; Tue, 17 Nov 2020 17:02:48 +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 AE0DD8C7A7; Tue, 17 Nov 2020 17:02:48 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAml8028053 for ; Tue, 17 Nov 2020 11:10:48 -0500 Received: by smtp.corp.redhat.com (Postfix) id AA0935B4B0; Tue, 17 Nov 2020 16:10:48 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id D099C5B4BB; Tue, 17 Nov 2020 16:10:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632666; 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=qylXKAqIG+kTbl3luWwwgNJqzV2SXcNgSvSXEqGE9+A=; b=MQb3oLyWU+SKYOGeyZKREpVkSxjuBuhhBrm/8J9x9LuHalAyfibi3rU8NxnZXWgQHR8fxx u/17ukOx3xbplLrLy29q6aMM9fqbFBw37+bBGZAXViRrDPL8ZrhMqvc8zBGVAuibnXpDLI mpx4YUnglUBgvvMcvIVzA9qJke8xOWw= X-MC-Unique: rLPqci54NZOn2NRIdDx89g-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 13/16] docs: add manpage for virtstoraged Date: Tue, 17 Nov 2020 16:10:24 +0000 Message-Id: <20201117161027.210543-14-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtstoraged.rst | 215 +++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtstoraged.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index fb62dc86a2..40f1fb849f 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -25,6 +25,7 @@ These daemons provide functionality to a single libvirt d= river * `virtnwfilterd(8) `__ - libvirt network filter manag= ement daemon * `virtqemud(8) `__ - libvirt QEMU management daemon * `virtsecretd(8) `__ - libvirt secret data management d= aemon +* `virtstoraged(8) `__ - libvirt storage pool managemen= t daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 1476722bde..9bc61c56cd 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -33,6 +33,7 @@ docs_man_files =3D [ { 'name': 'virtproxyd', 'section': '8', 'install': conf.has('WITH_LIBVIR= TD') }, { 'name': 'virtqemud', 'section': '8', 'install': conf.has('WITH_QEMU') = }, { 'name': 'virtsecretd', 'section': '8', 'install': conf.has('WITH_SECRE= TS') }, + { 'name': 'virtstoraged', 'section': '8', 'install': conf.has('WITH_STOR= AGE') }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtstoraged.rst b/docs/manpages/virtstoraged.rst new file mode 100644 index 0000000000..1ca0b394bc --- /dev/null +++ b/docs/manpages/virtstoraged.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtstoraged +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +-------------------------------------- +libvirt storage pool management daemon +-------------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtstoraged`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtstoraged`` program is a server side daemon component of the libv= irt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for storage +pools. + +The ``virtstoraged`` daemon only listens for requests on a local Unix doma= in +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtstoraged`` does not interrupt running guests. Guests cont= inue to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtstoraged`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtstoraged.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtstoraged.socket virtstoraged-ro.socket \ + virtstoraged-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtstoraged`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtstoraged.conf`` + +The default configuration file used by ``virtstoraged``, unless overridden= on the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtstoraged-sock`` +* ``@RUNSTATEDIR@/libvirt/virtstoraged-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtstoraged-admin-sock`` + +The sockets ``virtstoraged`` will use. + +The TLS **Server** private key ``virtstoraged`` will use. + +* ``@RUNSTATEDIR@/virtstoraged.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtstoraged.conf`` + +The default configuration file used by ``virtstoraged``, unless overridden= on the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtstoraged-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtstoraged-admin-sock`` + +The sockets ``virtstoraged`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtstoraged.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtstoraged`` w= ill use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtstoraged`` w= ill use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtstoraged``: + +:: + + # virtstoraged --version + virtstoraged (libvirt) @ + + +To start ``virtstoraged``, instructing it to daemonize and create a PID fi= le: + +:: + + # virtstoraged -d + # ls -la @RUNSTATEDIR@/virtstoraged.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtstoraged.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtstoraged`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvstorage.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632671; cv=none; d=zohomail.com; s=zohoarc; b=kttMT6Z8Z97qufN62U5UUsmgcQzjt02mfIZV3MJzhOrRALmgb5oUfNGDKuX9zP/B3dwESQoVFn9rYRPB/CUNQ4QQqvqcKbXr/JN6Zfxw+4WFOxwrXKMTLH+VwQLjKOvuDpbPTSwFFGaMULe7IJbNBzx+rVf9AA9mb7nWoMMDGzI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632671; 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=hE/Q0X7Pg3TmCNSuSTSc5V5J6Mq6OdPnfFSy5fe0VP0=; b=JmC+Nwm6XFVa/k8xN4Dh8u3PD7BgH3+brOm7qSwRYGEPu17nbmTb6r0XSkVXzFaMB+Dm3m8BiCVjWCsoj6KwyxTSqwgoZP1x+dnPhcrYvErDgFuMOYs4SVFimZX1iJ9zD5Cr8aC4a0KVowy6XK4NBKA53tPVXMvfragr376mWso= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632671538230.4038710686533; Tue, 17 Nov 2020 09:04:31 -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-12-vs3aVCxEOf-8G4Rvaw60Gw-1; Tue, 17 Nov 2020 12:02:57 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 159561882FA0; Tue, 17 Nov 2020 17:02:52 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E787C5C3E1; Tue, 17 Nov 2020 17:02:51 +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 AF5491832FF5; Tue, 17 Nov 2020 17:02:51 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAnXA028066 for ; Tue, 17 Nov 2020 11:10:49 -0500 Received: by smtp.corp.redhat.com (Postfix) id DF8015B4A2; Tue, 17 Nov 2020 16:10:49 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 16E5D5B4BB; Tue, 17 Nov 2020 16:10:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632670; 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=hE/Q0X7Pg3TmCNSuSTSc5V5J6Mq6OdPnfFSy5fe0VP0=; b=COr9ylxhB5NHZHVebyS1e4UxbCmvPgTcorQVja7353CVtMxm2I1WHJWDUwuDaB87dhlapK 8a4USIZZIPIdTMcQNg1VptWM1YkNol/qaiGVBjvJX5VcXagj8dmOwsTMswLk4qXn+yge+/ VRTA0MKUK+c6wjMo8RbVYOOFSsojrXM= X-MC-Unique: vs3aVCxEOf-8G4Rvaw60Gw-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 14/16] docs: add manpage for virtvboxd Date: Tue, 17 Nov 2020 16:10:25 +0000 Message-Id: <20201117161027.210543-15-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtvboxd.rst | 213 ++++++++++++++++++++++++++++++++++++ 3 files changed, 215 insertions(+) create mode 100644 docs/manpages/virtvboxd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 40f1fb849f..fa983c6cbd 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -26,6 +26,7 @@ These daemons provide functionality to a single libvirt d= river * `virtqemud(8) `__ - libvirt QEMU management daemon * `virtsecretd(8) `__ - libvirt secret data management d= aemon * `virtstoraged(8) `__ - libvirt storage pool managemen= t daemon +* `virtvboxd(8) `__ - libvirt VirtualBox management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 9bc61c56cd..af10d3a2c5 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -34,6 +34,7 @@ docs_man_files =3D [ { 'name': 'virtqemud', 'section': '8', 'install': conf.has('WITH_QEMU') = }, { 'name': 'virtsecretd', 'section': '8', 'install': conf.has('WITH_SECRE= TS') }, { 'name': 'virtstoraged', 'section': '8', 'install': conf.has('WITH_STOR= AGE') }, + { 'name': 'virtvboxd', 'section': '8', 'install': conf.has('WITH_VBOX') = }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtvboxd.rst b/docs/manpages/virtvboxd.rst new file mode 100644 index 0000000000..d452766b3e --- /dev/null +++ b/docs/manpages/virtvboxd.rst @@ -0,0 +1,213 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D +virtvboxd +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +------------------------------------ +libvirt VirtualBox management daemon +------------------------------------ + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtvboxd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtvboxd`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for Virtual= Box +virtual machines. + +The ``virtvboxd`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtvboxd`` does not interrupt running guests. Guests continu= e to +operate and changes in their state will generally be picked up automatical= ly +during startup. + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtvboxd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtvboxd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtvboxd.socket virtvboxd-ro.socket \ + virtvboxd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtvboxd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtvboxd.conf`` + +The default configuration file used by ``virtvboxd``, unless overridden on= the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtvboxd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtvboxd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtvboxd-admin-sock`` + +The sockets ``virtvboxd`` will use. + +The TLS **Server** private key ``virtvboxd`` will use. + +* ``@RUNSTATEDIR@/virtvboxd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtvboxd.conf`` + +The default configuration file used by ``virtvboxd``, unless overridden on= the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtvboxd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtvboxd-admin-sock`` + +The sockets ``virtvboxd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtvboxd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtvboxd`` will= use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtvboxd`` will= use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtvboxd``: + +:: + + # virtvboxd --version + virtvboxd (libvirt) @ + + +To start ``virtvboxd``, instructing it to daemonize and create a PID file: + +:: + + # virtvboxd -d + # ls -la @RUNSTATEDIR@/virtvboxd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtvboxd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtvboxd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvvbox.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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=1605632561; cv=none; d=zohomail.com; s=zohoarc; b=fF/4KHxmISA7jiQhOMPrTufXZkuU8MOx9Tx+GkiaDZ6HGrQJSs/Ls98fnGL9E/QJHxHjul3z4sCSEeI6JnwQXVBIpBttqZ5GMk4LEdkt6BkMrLQkAOWwvuwpYKzgqQ/eMw7poQ/vK38wwGH5sPHDEYMHn3ehC2BUVKMQKDINSKI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632561; 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=dbDwOLrfbaArWNuNCIp8sBycSCQCmQEaE5l34nDr/AA=; b=Rrjj7urP6/SPhNIE2+NqnPkeneBdOHzP/il59J8PqsPkjuNHsPHX58TbICvVQCBqoTTSxdlf8IT2sz6EwLHPB+apHk6Jak72yYolNrCYXVvdwWVLOtfMhrtUvyBCc/9yi20LCGazYt1UgD57+Bvprw9ylroENUFaU0djjwkRMfo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1605632561032371.6102827880403; Tue, 17 Nov 2020 09:02:41 -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-107-zpCPV1P6M0iOLIaGngFC3g-1; Tue, 17 Nov 2020 12:02:31 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 42E388030AD; Tue, 17 Nov 2020 17:02:25 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1C9DA60C43; Tue, 17 Nov 2020 17:02:25 +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 D75C31826D38; Tue, 17 Nov 2020 17:02:24 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGAsAx028080 for ; Tue, 17 Nov 2020 11:10:54 -0500 Received: by smtp.corp.redhat.com (Postfix) id 69C925B4B6; Tue, 17 Nov 2020 16:10:54 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4FD575B4B0; Tue, 17 Nov 2020 16:10:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632559; 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=dbDwOLrfbaArWNuNCIp8sBycSCQCmQEaE5l34nDr/AA=; b=U7UcymnLG/fll1AtK1SUMyo6Kp7jmtMGvCi7gw0QYrJ+Ow3CBLb/RDgN8cghrH0kuYF0/c 39fN1Pb6gZU2mZQx9xyPMdGJnIe+LFn0jJz0Lae0xKmp7t0/yqWi/Mr1M7PB/e4N89eiek vRFcpcUDu5XvrxmUlBKcxu+TXW6ii2I= X-MC-Unique: zpCPV1P6M0iOLIaGngFC3g-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 15/16] docs: add manpage for virtvzd Date: Tue, 17 Nov 2020 16:10:26 +0000 Message-Id: <20201117161027.210543-16-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtvzd.rst | 215 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtvzd.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index fa983c6cbd..4e351722a5 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -27,6 +27,7 @@ These daemons provide functionality to a single libvirt d= river * `virtsecretd(8) `__ - libvirt secret data management d= aemon * `virtstoraged(8) `__ - libvirt storage pool managemen= t daemon * `virtvboxd(8) `__ - libvirt VirtualBox management daemon +* `virtvzd(8) `__ - libvirt Virtuozzo management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index af10d3a2c5..9c3431c95c 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -35,6 +35,7 @@ docs_man_files =3D [ { 'name': 'virtsecretd', 'section': '8', 'install': conf.has('WITH_SECRE= TS') }, { 'name': 'virtstoraged', 'section': '8', 'install': conf.has('WITH_STOR= AGE') }, { 'name': 'virtvboxd', 'section': '8', 'install': conf.has('WITH_VBOX') = }, + { 'name': 'virtvzd', 'section': '8', 'install': conf.has('WITH_VZ') }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtvzd.rst b/docs/manpages/virtvzd.rst new file mode 100644 index 0000000000..7e776026f8 --- /dev/null +++ b/docs/manpages/virtvzd.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D +virtvzd +=3D=3D=3D=3D=3D=3D=3D + +----------------------------------- +libvirt Virtuozzo management daemon +----------------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtvzd`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtvzd`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for Virtuoz= zo +virtual machines. + +The ``virtvzd`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtvzd`` does not interrupt running guests. Guests continue = to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtvzd`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtvzd.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtvzd.socket virtvzd-ro.socket \ + virtvzd-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtvzd`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtvzd.conf`` + +The default configuration file used by ``virtvzd``, unless overridden on t= he +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtvzd-sock`` +* ``@RUNSTATEDIR@/libvirt/virtvzd-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtvzd-admin-sock`` + +The sockets ``virtvzd`` will use. + +The TLS **Server** private key ``virtvzd`` will use. + +* ``@RUNSTATEDIR@/virtvzd.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtvzd.conf`` + +The default configuration file used by ``virtvzd``, unless overridden on t= he +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtvzd-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtvzd-admin-sock`` + +The sockets ``virtvzd`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtvzd.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtvzd`` will u= se +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtvzd`` will u= se +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtvzd``: + +:: + + # virtvzd --version + virtvzd (libvirt) @ + + +To start ``virtvzd``, instructing it to daemonize and create a PID file: + +:: + + # virtvzd -d + # ls -la @RUNSTATEDIR@/virtvzd.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtvzd.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtvzd`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvvz.html `_ --=20 2.28.0 From nobody Wed Apr 24 20:58:43 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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=1605632562; cv=none; d=zohomail.com; s=zohoarc; b=SyLXenCJHJOH9dRzjdnAMR1a3Iz6biyrz5DTl6ONCjjeLKmTpmxhmh/P7ln9vMU23T7hmYx0rhfO0xn6i+9BvvhXeE2ElCPRLtdaIK5POfl6YnxZRKeWncuHLCmOnY09FIeN9p9PzNULtxv//lZS1ZfhIo9V6Fx312TrDfeb6MM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1605632562; 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=KpKNNx5W2AooCF550wMGGjD8VRQXV9l1BhG0doiQ4Tw=; b=D+ENg00flkE8lk8J40g2GeKiBrHDqT8XrPwkKq/ahqNBvmi9cwCdiOdQJmhCQxvGMJRVlrYVIEagZ6+/vi1PfIVWpAii4wCUTQba9K9mohEaj3mH7sU1LNLX8NmzLqoxAsgExNXaS1iw7QBydN/kVblEUrhYdjAi0ZW7OeWj9fg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 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-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1605632562269475.24603907644894; Tue, 17 Nov 2020 09:02:42 -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-206-B2dP8DIaPa2ub8gdjfbI8Q-1; Tue, 17 Nov 2020 12:02:35 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3FA278730A0; Tue, 17 Nov 2020 17:02:28 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 19A9A5C1CF; Tue, 17 Nov 2020 17:02:28 +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 D54BD1826D3C; Tue, 17 Nov 2020 17:02:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 0AHGB2wr028105 for ; Tue, 17 Nov 2020 11:11:02 -0500 Received: by smtp.corp.redhat.com (Postfix) id 06A925B4A2; Tue, 17 Nov 2020 16:11:02 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-115-10.ams2.redhat.com [10.36.115.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 15AFB5B4B6; Tue, 17 Nov 2020 16:10:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1605632559; 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=KpKNNx5W2AooCF550wMGGjD8VRQXV9l1BhG0doiQ4Tw=; b=gHP7agKhoZnV9x+M+/O5+y6dcf3CJ0L3y5sUF1ItE5UKDJuDi4KmlrElTBwN0hVjMx+93d A/yyd6Ifk+/3gGeqAPgc35X8ZlYzcDklZ21LwxK4y6nM2/5xny8KMrlp/c+8uWQtdxJiYd uYBoM/k+flsSqhOCKl4FzU0b5knKADk= X-MC-Unique: B2dP8DIaPa2ub8gdjfbI8Q-1 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Subject: [libvirt PATCH 16/16] docs: add manpage for virtxend Date: Tue, 17 Nov 2020 16:10:27 +0000 Message-Id: <20201117161027.210543-17-berrange@redhat.com> In-Reply-To: <20201117161027.210543-1-berrange@redhat.com> References: <20201117161027.210543-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com 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.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) This is an adaptation of the libvirtd manpage. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Neal Gompa --- docs/manpages/index.rst | 1 + docs/manpages/meson.build | 1 + docs/manpages/virtxend.rst | 215 +++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/manpages/virtxend.rst diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst index 4e351722a5..fb4a36d46a 100644 --- a/docs/manpages/index.rst +++ b/docs/manpages/index.rst @@ -28,6 +28,7 @@ These daemons provide functionality to a single libvirt d= river * `virtstoraged(8) `__ - libvirt storage pool managemen= t daemon * `virtvboxd(8) `__ - libvirt VirtualBox management daemon * `virtvzd(8) `__ - libvirt Virtuozzo management daemon +* `virtxend(8) `__ - libvirt Xen management daemon =20 Tools =3D=3D=3D=3D=3D diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build index 9c3431c95c..800c3692fb 100644 --- a/docs/manpages/meson.build +++ b/docs/manpages/meson.build @@ -36,6 +36,7 @@ docs_man_files =3D [ { 'name': 'virtstoraged', 'section': '8', 'install': conf.has('WITH_STOR= AGE') }, { 'name': 'virtvboxd', 'section': '8', 'install': conf.has('WITH_VBOX') = }, { 'name': 'virtvzd', 'section': '8', 'install': conf.has('WITH_VZ') }, + { 'name': 'virtxend', 'section': '8', 'install': conf.has('WITH_XEN') }, ] =20 foreach name : keycode_list diff --git a/docs/manpages/virtxend.rst b/docs/manpages/virtxend.rst new file mode 100644 index 0000000000..cf0128d3ff --- /dev/null +++ b/docs/manpages/virtxend.rst @@ -0,0 +1,215 @@ +=3D=3D=3D=3D=3D=3D=3D=3D +virtxend +=3D=3D=3D=3D=3D=3D=3D=3D + +----------------------------- +libvirt Xen management daemon +----------------------------- + +:Manual section: 8 +:Manual group: Virtualization Support + +.. contents:: + +SYNOPSIS +=3D=3D=3D=3D=3D=3D=3D=3D + +``virtxend`` [*OPTION*]... + + +DESCRIPTION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtxend`` program is a server side daemon component of the libvirt +virtualization management system. + +It is one of a collection of modular daemons that replace functionality +previously provided by the monolithic ``libvirtd`` daemon. + +This daemon runs on virtualization hosts to provide management for Xen vir= tual +machines. + +The ``virtxend`` daemon only listens for requests on a local Unix domain +socket. Remote off-host access and backwards compatibility with legacy +clients expecting ``libvirtd`` is provided by the ``virtproxy`` daemon. + +Restarting ``virtxend`` does not interrupt running guests. Guests continue= to +operate and changes in their state will generally be picked up automatical= ly +during startup. None the less it is recommended to avoid restarting with +running guests whenever practical. + + +SYSTEM SOCKET ACTIVATION +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The ``virtxend`` daemon is capable of starting in two modes. + +In the traditional mode, it will create and listen on UNIX sockets itself. + +In socket activation mode, it will rely on systemd to create and listen +on the UNIX sockets and pass them as pre-opened file descriptors. In this +mode most of the socket related config options in +``/etc/libvirt/virtxend.conf`` will no longer have any effect. + +Socket activation mode is generally the default when running on a host +OS that uses systemd. To revert to the traditional mode, all the socket +unit files must be masked: + +:: + + $ systemctl mask virtxend.socket virtxend-ro.socket \ + virtxend-admin.socket + + +OPTIONS +=3D=3D=3D=3D=3D=3D=3D + +``-h``, ``--help`` + +Display command line help usage then exit. + +``-d``, ``--daemon`` + +Run as a daemon & write PID file. + +``-f``, ``--config *FILE*`` + +Use this configuration file, overriding the default value. + +``-p``, ``--pid-file *FILE*`` + +Use this name for the PID file, overriding the default value. + +``-t``, ``--timeout *SECONDS*`` + +Exit after timeout period (in seconds), provided there are neither any cli= ent +connections nor any running domains. + +``-v``, ``--verbose`` + +Enable output of verbose messages. + +``--version`` + +Display version information then exit. + + +SIGNALS +=3D=3D=3D=3D=3D=3D=3D + +On receipt of ``SIGHUP`` ``virtxend`` will reload its configuration. + + +FILES +=3D=3D=3D=3D=3D + +When run as *root* +------------------ + +* ``@SYSCONFDIR@/libvirt/virtxend.conf`` + +The default configuration file used by ``virtxend``, unless overridden on = the +command line using the ``-f`` | ``--config`` option. + +* ``@RUNSTATEDIR@/libvirt/virtxend-sock`` +* ``@RUNSTATEDIR@/libvirt/virtxend-sock-ro`` +* ``@RUNSTATEDIR@/libvirt/virtxend-admin-sock`` + +The sockets ``virtxend`` will use. + +The TLS **Server** private key ``virtxend`` will use. + +* ``@RUNSTATEDIR@/virtxend.pid`` + +The PID file to use, unless overridden by the ``-p`` | ``--pid-file`` opti= on. + + +When run as *non-root* +---------------------- + +* ``$XDG_CONFIG_HOME/libvirt/virtxend.conf`` + +The default configuration file used by ``virtxend``, unless overridden on = the +command line using the ``-f``|``--config`` option. + +* ``$XDG_RUNTIME_DIR/libvirt/virtxend-sock`` +* ``$XDG_RUNTIME_DIR/libvirt/virtxend-admin-sock`` + +The sockets ``virtxend`` will use. + +* ``$XDG_RUNTIME_DIR/libvirt/virtxend.pid`` + +The PID file to use, unless overridden by the ``-p``|``--pid-file`` option. + + +If ``$XDG_CONFIG_HOME`` is not set in your environment, ``virtxend`` will = use +``$HOME/.config`` + +If ``$XDG_RUNTIME_DIR`` is not set in your environment, ``virtxend`` will = use +``$HOME/.cache`` + + +EXAMPLES +=3D=3D=3D=3D=3D=3D=3D=3D + +To retrieve the version of ``virtxend``: + +:: + + # virtxend --version + virtxend (libvirt) @ + + +To start ``virtxend``, instructing it to daemonize and create a PID file: + +:: + + # virtxend -d + # ls -la @RUNSTATEDIR@/virtxend.pid + -rw-r--r-- 1 root root 6 Jul 9 02:40 @RUNSTATEDIR@/virtxend.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-2020 Red Hat, Inc., and the authors listed in the +libvirt AUTHORS file. + + +LICENSE +=3D=3D=3D=3D=3D=3D=3D + +``virtxend`` 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 + +virsh(1), libvirtd(8), +`https://www.libvirt.org/daemons.html `_, +`https://www.libvirt.org/drvxen.html = `_ --=20 2.28.0