[libvirt] [PATCH 6/6] docs: add page describing the libvirt daemons

Fri Nov 8 11:21:12 UTC 2019

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é <berrange at redhat.com>
---
 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 = \
   news.html.in
 dot_html_in = \
   $(notdir $(wildcard $(srcdir)/*.html.in))
+dot_rst = \
+  $(notdir $(wildcard $(srcdir)/*.rst))
+dot_rst_html_in = \
+  $(dot_rst:%.rst=%.html)
 dot_html = \
   $(dot_html_generated_in:%.html.in=%.html) \
-  $(dot_html_in:%.html.in=%.html)
+  $(dot_html_in:%.html.in=%.html) \
+  $(dot_rst_html_in:%.html.in=%.html)
 
 xml = \
   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 @@
+===============
+Libvirt Daemons
+===============
+
+.. 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
+========================
+
+Traditionally libvirt has provided a single monolithic daemon called `libvirtd`
+which exposed support for all the stateful drivers, both primary hypervisor
+drivers and secondary supporting drivers. It also enables secure remote access
+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 root
+  shell**. Suitable `authentication mechanisms <auth.html>`_ **must be enabled**
+  to secure it against untrustworthy clients/users.
+
+* *Session mode* - `libvirtd` is running as any non-root user account, enabling
+  access to a more restricted range of functionality. Only client apps/users
+  running under **the same UID are permitted to connect**, thus a connection
+  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 libvirt
+  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 socket
+  gives the ability to query the existance of objects and monitor some aspects
+  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 does
+  not use TLS, an `authentication mechanism <auth.html>`_ 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 control
+  can be enforced either through validation of `x509 certificates
+  <tlscerts.html>`_, and/or by enabling an `authentication mechanism
+  <auth.html>`_.
+
+When running in session mode, `libvirtd` exposes two UNIX domain sockets
+
+* `$XDG_RUNTIME_DIR/libvirt/libvirt-sock` - the primary socket for accessing
+  libvirt APIs, with full read-write privileges. A connection to this socket
+  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 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.
+
+Notice that the session mode does not have a separate read-only socket. Since
+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 control
+  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 recommended
+  to be started on boot by default.
+
+* `libvirtd-admin.socket` - the unit file corresponding to the administrative
+  UNIX socket `/var/run/libvirt/libvirt-sock-admin`. This socket is recommended
+  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 mechanism.
+
+* `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 hosts
+the UNIX socket units should be enabled by default. When upgrading an existing
+host from a previous version of libvirt, the socket unit files will be masked
+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 `SocketGroup`
+  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 via 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 activation
+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
+======================
+
+Helper daemons
+==============
+
+There are some other special purpose daemons used for certain administrative
+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 other
+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 performing
+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 updates
+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 `SIGUSR1`
+
+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 @@
         <dt><a href="migration.html">Migration</a></dt>
         <dd>Migrating guests between machines</dd>
 
+        <dt><a href="daemons.html">Daemons</a></dt>
+        <dd>Overview of the daemons provided by libvirt</dd>
+
         <dt><a href="remote.html">Remote access</a></dt>
         <dd>Enable remote access over TCP</dd>
 
-- 
2.23.0


