Re: [libvirt PATCH] 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/daemons.rst | 682 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 2 files changed, 685 insertions(+) create mode 100644 docs/daemons.rst diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..a74b228025 --- /dev/null +++ b/docs/daemons.rst @@ -0,0 +1,682 @@ +=============== +Libvirt Daemons +=============== + +.. contents:: + +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. + +Architectural options +===================== + +Monolithic vs modular daemons +----------------------------- + +Traditionally libvirt 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. + +Work is underway for the monolithic daemon to be replaced by a new set of +modular daemons ``virt${DRIVER}d``, each one servicing a single stateful +driver. A further ``virtproxyd`` daemon will provide secure remote access, as +well as backcompatibility for clients using the UNIX socket path of the +monolithic daemon. + +The change to modular daemons should not affect API functionality used by +management applications. It will, however, have an impact on host provisioning +tools since there are new systemd services and configuration files to be +managed. + +Currently both monolithic and modular daemons are built by default, but the RPC +client still prefers connecting to the monolithic daemon. It is intended to +switch the RPC client to prefer the modular daemons in the near future. At +least 1 year after this switch (but not more than 2 years), the monolithic +daemon will be deleted entirely. + +Operating modes +--------------- + +The libvirt daemons, whether monolithic or modular, can often operate in two +modes + +* *System mode* - the daemon is running as the root user account, enabling + access to its full range of functionality. A read-write connection to + daemons in system mode **typically 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* - the daemon is running as any non-root user account, + providing 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. + + Not all drivers support session mode and as such the corresponding + modular daemon may not support running in this mode + + +Monolithic driver daemon +======================== + +The monolithic daemon is known as ``libvirtd`` and has historically been the +default in libvirt. It is configured via the file ``/etc/libvirt/libvirtd.conf`` + + +Monolithic 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

+NB, some distros will use ``/run`` instead of ``/var/run``. + +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-admin-sock`` - 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``.

+ + +Monolithic 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

+--------------- + +When running in system mode, ``virt${DRIVER}d`` exposes three UNIX domain +sockets: + +* ``/var/run/libvirt/virt${DRIVER}d-sock`` - the primary socket for accessing + libvirt APIs, with full read-write privileges. For many of the daemons, 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/virt${DRIVER}d-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/virt${DRIVER}d-admin-sock`` - 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. + +NB, some distros will use ``/run`` instead of ``/var/run``. + +When running in session mode, ``virt${DRIVER}d`` exposes two UNIX domain sockets + +* ``$XDG_RUNTIME_DIR/libvirt/virt${DRIVER}d-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/virt${DRIVER}d-admin-sock`` - 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``. + +Modular Systemd Integration +--------------------------- + +When the ``virt${DRIVER}d`` 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 virt${DRIVER}d + +* ``virt${DRIVER}d.service`` - the main unit file for launching the + ``virt${DRIVER}d daemon`` in system mode. The command line arguments passed + can be configured by editting ``/etc/sysconfig/virt${DRIVER}d``. This is

+Switching to modular daemons +---------------------------- + +If a host is currently set to use the monolithic ``libvirtd`` daemon and needs +to be migrated to the monolithic daemons a number of services need to be +changed. The steps below outline the process on hosts using the systemd init +service. + +While it is technically possible todo this while virtual machines are running,

+Proxy Systemd Integration +------------------------- + +When the ``virtproxyd`` 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 virtproxyd + +* ``virtproxyd.service`` - the main unit file for launching the virtproxyd + daemon in system mode. The command line arguments passed can be configured by + editting ``/etc/sysconfig/virtproxyd``. This is typically only needed to

+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 virtproxyd 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 +``virtproxyd.conf`` are no longer honoured. Instead these settings must be +controlled via the system unit files. Refer to the earlier documentation on +the ``libvirtd`` service socket configuration for further information.

+ +Logging Systemd Integration +--------------------------- + +When the ``virtlogd`` 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 virtlogd + +* ``virtlogd.service`` - the main unit file for launching the + ``virtlogd daemon`` in system mode. The command line arguments passed + can be configured by editting ``/etc/sysconfig/virtlogd``. This is

+Locking Systemd Integration +--------------------------- + +When the ``virtlockd`` 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 virtlockd + +* ``virtlockd.service`` - the main unit file for launching the + ``virtlockd daemon`` in system mode. The command line arguments passed + can be configured by editting ``/etc/sysconfig/virtlockd``. This is