From nobody Sun Feb 8 04:11:25 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zoho.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1573212104; cv=none; d=zoho.com; s=zohoarc; b=RjwW5bYd+9LGiIFBLzqqoRRPE50ljEaOar9XeFWXZeVSB1pQBSbtyM4g0ZLiQYWmqxJSGjGO+HQqBlR94ql69uexKrz0faI20gs4X7fhkKZzfV/t77J67HAb9889DJO1OMGS3JQDqIdcYxox0vgU/FEGbuoic7EH8q3Xe/LgTtc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1573212104; 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=hhwavviWRkPOm7VzD/VohsASUBK8W9/cQhh2QxttMHU=; b=hMvch2wRvP5PG2zR1W4v+3mIpdeDQFJ5D8jMxaBn3mlraupDrv9iWEH9Rt+2RMMKn/JGKA7p46kYvw1JBxWK3n+MACjyEjr+Xrr6+W+kYssWnUyOJIuCTaPPkXDVgP+TB3p14PUy5DJ83Jo0jJRrrwwkuto0xZ+ahShg90oGxno= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass; spf=pass (zoho.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-2.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1573212104833363.9644793327998; Fri, 8 Nov 2019 03:21:44 -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-286-EtAk82jwMU2M4qnEmRyQ1w-1; Fri, 08 Nov 2019 06:21:40 -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 C3C9B1005516; Fri, 8 Nov 2019 11:21:34 +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 97044600CA; Fri, 8 Nov 2019 11:21:34 +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 54F9E4E567; Fri, 8 Nov 2019 11:21:34 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xA8BLR1K029269 for ; Fri, 8 Nov 2019 06:21:27 -0500 Received: by smtp.corp.redhat.com (Postfix) id 2E39E60C18; Fri, 8 Nov 2019 11:21:27 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-63.ams2.redhat.com [10.36.112.63]) by smtp.corp.redhat.com (Postfix) with ESMTP id 65EF560CD0; Fri, 8 Nov 2019 11:21:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1573212103; 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=hhwavviWRkPOm7VzD/VohsASUBK8W9/cQhh2QxttMHU=; b=X4IBvseKTZxaHKSQYJYayi+kG57h26lZgcOHAXNhME0AwAIfC0q03JCt2FedbIou4AaBHf xdmSoxLdjlg4UReMlUBS5CVDaFbKfRuA3usHDHM225UKaNMjrBSyloZZfASISKeIwiGtzX yw9myOFa4mzBGTgrjNVcTnw0gssiTr4= From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Date: Fri, 8 Nov 2019 11:21:12 +0000 Message-Id: <20191108112112.643266-7-berrange@redhat.com> In-Reply-To: <20191108112112.643266-1-berrange@redhat.com> References: <20191108112112.643266-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 6/6] docs: add page describing the libvirt daemons 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 X-MC-Unique: EtAk82jwMU2M4qnEmRyQ1w-1 X-Mimecast-Spam-Score: 0 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Now that we have more than just the libvirtd daemon, we should be explaining to users what they are all for & important aspects of their configuration. Signed-off-by: Daniel P. Berrang=C3=A9 --- docs/Makefile.am | 7 +- docs/daemons.rst | 209 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 docs/daemons.rst diff --git a/docs/Makefile.am b/docs/Makefile.am index 2b04f3b362..3dd61640b5 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -128,9 +128,14 @@ dot_html_generated_in =3D \ news.html.in dot_html_in =3D \ $(notdir $(wildcard $(srcdir)/*.html.in)) +dot_rst =3D \ + $(notdir $(wildcard $(srcdir)/*.rst)) +dot_rst_html_in =3D \ + $(dot_rst:%.rst=3D%.html) dot_html =3D \ $(dot_html_generated_in:%.html.in=3D%.html) \ - $(dot_html_in:%.html.in=3D%.html) + $(dot_html_in:%.html.in=3D%.html) \ + $(dot_rst_html_in:%.html.in=3D%.html) =20 xml =3D \ libvirt-api.xml \ diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..51d4153b99 --- /dev/null +++ b/docs/daemons.rst @@ -0,0 +1,209 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Daemons +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: Topics + +A libvirt deployment for accessing one of the stateful drivers will require +one or more daemons to be deployed on the virtualization host. There are a +number of ways the daemons can be configured which will be outlined in this +page + +Monolithic driver daemon +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Traditionally libvirt has provided a single monolithic daemon called `libv= irtd` +which exposed support for all the stateful drivers, both primary hypervisor +drivers and secondary supporting drivers. It also enables secure remote ac= cess +from clients running off host. + +Operating modes +--------------- + +The daemon can operate in two modes + +* *System mode* - `libvirtd` is running as the root user account, enabling + access to its full range of functionality. A read-write connection to + `libvirtd` in system mode **implies privileges equivalent to having a ro= ot + shell**. Suitable `authentication mechanisms `_ **must be ena= bled** + to secure it against untrustworthy clients/users. + +* *Session mode* - `libvirtd` is running as any non-root user account, ena= bling + access to a more restricted range of functionality. Only client apps/use= rs + running under **the same UID are permitted to connect**, thus a connecti= on + does not imply any elevation of privileges. + + +Sockets +------- + +When running in system mode, `libvirtd` exposes three UNIX domain sockets,= and +optionally, one or two TCP sockets + +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvi= rt + APIs, with full read-write privileges. A connection to this socket gives= the + client privileges that are equivalent to having a root shell. This is the + socket that most management applications connect to by default. + +* `/var/run/libvirt/libvirt-sock-ro` - the secondary socket for accessing + libvirt APIs, with limited read-only privileges. A connection to this so= cket + gives the ability to query the existance of objects and monitor some asp= ects + of their operation. This is the socket that most management applications + connect to when requesting read only mode. Typically this is what a + monitoring app would use. + +* `/var/run/libvirt/libvirt-sock-admin` - the administrative socket for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. + +* `TCP 16509` - the non-TLS socket for remotely accessing the libvirt APIs, + with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. Since it d= oes + not use TLS, an `authentication mechanism `_ that provides + encryption must be used. Only the GSSAPI/Kerberos mechanism is capable of + satisfying this requirement. In general applications should not use this + socket except for debugging in a development/test environment. + +* `TCP 16514` - the TLS socket for remotely accessing the libvirt APIs, + with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. Access con= trol + can be enforced either through validation of `x509 certificates + `_, and/or by enabling an `authentication mechanism + `_. + +When running in session mode, `libvirtd` exposes two UNIX domain sockets + +* `$XDG_RUNTIME_DIR/libvirt/libvirt-sock` - the primary socket for accessi= ng + libvirt APIs, with full read-write privileges. A connection to this sock= et + does not alter the privileges that the client already has. This is the + socket that most management applications connect to by default. + +* `$XDG_RUNTIME_DIR/libvirt/libvirt-sock-admin` - the administrative socke= t for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. + +Notice that the session mode does not have a separate read-only socket. Si= nce +the clients must be running as the same user as the daemon itself, there is +not any security benefit from attempting to enforce a read-only mode. + +`$XDG_RUNTIME_DIR` commonly points to a per-user private location on tmpfs, +such as `/run/user/$UID`. + +Systemd Integration +------------------- + +When the `libvirtd` daemon is managed by `systemd` a number of desirable +features are available, most notably socket activation. + +Libvirt ships a number of unit files for controlling libvirtd + +* `libvirtd.service` - the main unit file for launching the libvirtd daemon + in system mode. The command line arguments passed can be configured by + editting `/etc/sysconfig/libvirtd`. This is typically only needed to con= trol + the use of the auto shutdown timeout value. It is recommended that this + the service unit be configured to start on boot. This is because various + libvirt drivers support autostart of their objects. If it is known that + autostart is not required, this unit can be left to start on demand. + +* `libvirtd.socket` - the unit file corresponding to the main read-write + UNIX socket `/var/run/libvirt/libvirt-sock`. This socket is recommended = to + be started on boot by default. + +* `libvirtd-ro.socket` - the unit file corresponding to the main read-write + UNIX socket `/var/run/libvirt/libvirt-sock-ro`. This socket is recommend= ed + to be started on boot by default. + +* `libvirtd-admin.socket` - the unit file corresponding to the administrat= ive + UNIX socket `/var/run/libvirt/libvirt-sock-admin`. This socket is recomm= ended + to be started on boot by default. + +* `libvirt-tcp.socket` - the unit file corresponding to the TCP 16509 port= for + non-TLS remote access. This socket should not be configured to start on = boot + until the administrator has configured a suitable authentication mechani= sm. + +* `libvirt-tls.socket` - the unit file corresponding to the TCP 16509 port= for + TLS remote access. This socket should not be configured to start on boot + until the administrator has deployed x509 certificates and optionally + configured a suitable authentication mechanism. + +The socket unit files are newly introduced in 5.6.0. On newly installed ho= sts +the UNIX socket units should be enabled by default. When upgrading an exis= ting +host from a previous version of libvirt, the socket unit files will be mas= ked +if libvirtd is currently configured to use the `--listen` argument, since = the +`--listen` argument is mutually exclusive with use of socket activation. + +When systemd socket activation is used a number of configuration settings = in +`libvirtd.conf` are no longer honoured. Instead these settings must be +controlled via the system unit files + +* `listen_tcp` - TCP socket usage is enabled by starting the + `libvirtd-tcp.socket` unit file. + +* `listen_tls` - TLS socket usage is enabled by starting the + `libvirtd-tls.socket` unit file. + +* `tcp_port` - Port for the non-TLS TCP socket, controlled via the + `ListenStream` parameter in the `libvirtd-tcp.socket` unit file. + +* `tls_port` - Port for the TLS TCP socket, controlled via the + `ListenStream` parameter in the `libvirtd-tls.socket` unit file. + +* `listen_addr` - IP address to listen on, independently controlled via the + `ListenStream` parameter in the `libvirtd-tcp.socket` or + `libvirtd-tls.socket` unit files. + +* `unix_sock_group` - UNIX socket group owner, controlled via the `SocketG= roup` + parameter in the `libvirtd.socket` and `libvirtd-ro.socket` unit files + +* `unix_sock_ro_perms` - read-only UNIX socket permissions, controlled via= the + `SocketMode` parameter in the `libvirtd-ro.socket` unit file + +* `unix_sock_rw_perms` - read-write UNIX socket permissions, controlled vi= a the + `SocketMode` parameter in the `libvirtd.socket` unit file + +* `unix_sock_admin_perms` - admin UNIX socket permissions, controlled via = the + `SocketMode` parameter in the `libvirtd-admin.socket` unit file + +* `unix_sock_dir` - directory in which all UNIX sockets are created + independently controlled via the `ListenStream` parameter in any of the + `libvirtd.socket`, `libvirtd-ro.socket` and `libvirtd-admin.socket` unit + files. + + +Systemd releases prior to version 227 lacked support for passing the activ= ation +socket unit names into the service. When using these old versions, the +`tcp_port`, `tls_port` and `unix_sock_dir` settings in `libvirtd.conf` must +be changed in lock-step with the equivalent settings in the unit files to +ensure that `libvirtd` can identify the sockets. + +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 + +Helper daemons +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +There are some other special purpose daemons used for certain administrati= ve +tasks in libvirt + +Logging daemon +-------------- + +The `virtlogd` daemon provides a service for managing log files associated= with +QEMU virtual machines. The QEMU process is given one or more pipes, the ot= her +end of which are owned by the `virtlogd` daemon. It will then write data on +those pipes to log files, while enforcing a maximum file size and performi= ng +log rollover at the size limit. + +Since the daemon holds open anoymous pipe file descriptors, it must never = be +stopped while any QEMU virtual machines are running. To enable software up= dates +to be applied, the daemon is capable of re-executing itself while keeping = all +file descriptors open. This can be triggered by sending the daemon `SIGUSR= 1` + +Systemd integration +~~~~~~~~~~~~~~~~~~~ + +Locking daemon +-------------- + diff --git a/docs/docs.html.in b/docs/docs.html.in index 4b59162e0f..e378279827 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -15,6 +15,9 @@
Migration
Migrating guests between machines
=20 +
Daemons
+
Overview of the daemons provided by libvirt
+
Remote access
Enable remote access over TCP
=20 --=20 2.23.0 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list