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

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(a)redhat.com&gt; --- 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