[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 + 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-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. + +* ``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>`__. + +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 + the use of the auto shutdown timeout value. It is recommended that this + 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-admin-sock``. This socket is + recommended to be started on boot by default. + +* ``libvirtd-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. + +* ``libvirtd-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 +====================== + +The modular daemons are named after the driver which they are running, with +the pattern ``virt${DRIVER}d`` and will become the default in future libvirt. +They are configured via the files ``/etc/libvirt/virt${DRIVER}d.conf`` + +The following modular daemons currently exist for hypervisor drivers + +* ``virtqemud`` - the QEMU management daemon, for running virtual machines + on UNIX platforms, optionally with KVM acceleration, in either system or + session mode +* ``virtxend`` - the Xen management daemon, for running virtual machines + on the Xen hypervisor, in system mode only +* ``virtlxcd`` - the Linux Container management daemon, for running LXC guests + in system mode only +* ``virtbhyved`` - the BHyve management daemon, for running virtual machines + on FreeBSD with the BHyve hypervisor, in system mode. +* ``virtvboxd`` - the VirtualBox management daemon, for running virtual machines + on UNIX platforms. + +The additional modular daemons service secondary drivers + +* ``virtinterfaced`` - the host NIC management daemon, in system mode only +* ``virtnetworkd`` - the virtual network management daemon, in system mode only +* ``virtnodedevd`` - the host physical device management daemon, in system mode + only +* ``virtnwfilterd`` - the host firewall management daemon, in system mode only +* ``virtsecretd`` - the host secret management daemon, in system or session mode +* ``virtstoraged`` - the host storage management daemon, in system or session + mode + + +Modular Sockets +--------------- + +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 + typically only needed to control the use of the auto shutdown timeout value. + It is recommended that this 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. + +* ``virt${DRIVER}d.socket`` - the unit file corresponding to the main read-write + UNIX socket ``/var/run/libvirt/virt${DRIVER}d-sock``. This socket is + recommended to be started on boot by default. + +* ``virt${DRIVER}d-ro.socket`` - the unit file corresponding to the main + read-write UNIX socket ``/var/run/libvirt/virt${DRIVER}d-sock-ro``. This + socket is recommended to be started on boot by default. + +* ``virt${DRIVER}d-admin.socket`` - the unit file corresponding to the + administrative UNIX socket ``/var/run/libvirt/virt${DRIVER}d-admin-sock``. + This socket is recommended to be started on boot by default. + +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 virt${DRIVER}d 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 +``virt${DRIVER}d.conf`` are no longer honoured. Instead these settings must be +controlled via the system unit files + +* ``unix_sock_group`` - UNIX socket group owner, controlled via the + ``SocketGroup`` parameter in the ``virt${DRIVER}d.socket`` and + ``virt${DRIVER}d-ro.socket`` unit files + +* ``unix_sock_ro_perms`` - read-only UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virt${DRIVER}d-ro.socket`` unit file + +* ``unix_sock_rw_perms`` - read-write UNIX socket permissions, controlled via + the ``SocketMode`` parameter in the ``virt${DRIVER}d.socket`` unit file + +* ``unix_sock_admin_perms`` - admin UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virt${DRIVER}d-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 + ``virt${DRIVER}d.socket``, ``virt${DRIVER}d-ro.socket`` and + ``virt${DRIVER}d-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 +``unix_sock_dir`` setting in ``virt${DRIVER}d.conf`` must be changed in +lock-step with the equivalent setting in the unit files to ensure that +``virt${DRIVER}d`` can identify the sockets. + + +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, +it is recommended that virtual machines be stopped or live migrated to a new +host first. + +#. Stop the current monolithic daemon and its socket units + + :: + + $ systemctl stop libvirtd.service + $ systemctl stop libvirtd{,-ro,-admin,-tcp,-tls}.socket + +#. Disable future start of the monolithic daemon + + :: + + $ systemctl disable libvirtd.service + $ systemctl disable libvirtd{,-ro,-admin,-tcp,-tls}.socket + + For stronger protection it is valid to use ``mask`` instead of ``disable`` + too. + +#. Enable the new daemons for the particular virtualizationd driver desired, + and any of the secondary drivers to accompany it. The following example + enables the QEMU driver and all the secondary drivers: + + :: + + $ for drv in qemu interface network nodedev nwfilter secret storage + do + systemctl unmask virt${drv}d.service + systemctl unmask virt${drv}d{,-ro,-admin}.socket + systemctl enable virt${drv}d.service + systemctl enable virt${drv}d{,-ro,-admin}.socket + done + +#. Start the sockets for the same set of daemons. There is no need to start the + services as they will get started when the first socket connection is + established + + :: + + $ for drv in qemu network nodedev nwfilter secret storage + do + systemctl start virt${drv}d{,-ro,-admin}.socket + done + +#. If connections from remote hosts need to be supported the proxy daemon + must be enabled and started + + :: + + $ systemctl unmask virtproxyd.service + $ systemctl unmask virtproxyd{,-ro,-admin}.socket + $ systemctl enable virtproxyd.service + $ systemctl enable virtproxyd{,-ro,-admin}.socket + $ systemctl start virtproxyd{,-ro,-admin}.socket + + The UNIX sockets allow for remote access using SSH tunneling. If ``libvirtd`` + had TCP or TLS sockets configured, those should be started too + + :: + + $ systemctl unmask virtproxyd-tls.socket + $ systemctl enable virtproxyd-tls.socket + $ systemctl start virtproxyd-tls.socket + + +Proxy 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`` + + +Proxy sockets +------------- + +When running in system mode, ``virtproxyd`` exposes three UNIX domain sockets, +and optionally, one or two TCP sockets. These sockets are identical to those +provided by the traditional ``libvirtd`` so refer to earlier documentation in +this page. + +When running in session mode, ``virtproxyd`` exposes two UNIX domain sockets, +which are again identical to those provided by ``libvirtd``. + +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 + control the use of the auto shutdown timeout value. + +* ``virtproxyd.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. + +* ``virtproxyd-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. + +* ``virtproxyd-admin.socket`` - the unit file corresponding to the + administrative UNIX socket ``/var/run/libvirt/libvirt-admin-sock``. This + socket is recommended to be started on boot by default. + +* ``virtproxyd-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. + +* ``virtproxyd-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 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 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`` + +Logging Sockets +--------------- + +When running in system mode, ``virtlogd`` exposes two UNIX domain sockets: + +* ``/var/run/libvirt/virtlogd-sock`` - the primary socket for accessing + libvirt APIs, with full read-write privileges. Access to the socket is + restricted to the root user. + +* ``/var/run/libvirt/virtlogd-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, ``virtlogd`` exposes two UNIX domain sockets + +* ``$XDG_RUNTIME_DIR/libvirt/virtlogd-sock`` - the primary socket for + accessing libvirt APIs, with full read-write privileges. Access to the + socket is restricted to the unprivileged user running the daemon. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlogd-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. + +``$XDG_RUNTIME_DIR`` commonly points to a per-user private location on tmpfs, +such as ``/run/user/$UID``. + +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 + typically only needed to control the use of the auto shutdown timeout value. + +* ``virtlogd.socket`` - the unit file corresponding to the main read-write + UNIX socket ``/var/run/libvirt/virtlogd-sock``. This socket is recommended + to be started on boot by default. + +* ``virtlogd-admin.socket`` - the unit file corresponding to the administrative + UNIX socket ``/var/run/libvirt/virtlogd-admin-sock``. This socket is + recommended to be started on boot by default. + +When systemd socket activation is used a number of configuration settings in +``virtlogd.conf`` are no longer honoured. Instead these settings must be +controlled via the system unit files + +* ``unix_sock_group`` - UNIX socket group owner, controlled via the + ``SocketGroup`` parameter in the ``virtlogd.socket`` and + ``virtlogd-ro.socket`` unit files + +* ``unix_sock_ro_perms`` - read-only UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virtlogd-ro.socket`` unit file + +* ``unix_sock_rw_perms`` - read-write UNIX socket permissions, controlled via + the ``SocketMode`` parameter in the ``virtlogd.socket`` unit file + +* ``unix_sock_admin_perms`` - admin UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virtlogd-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 + ``virtlogd.socket`` and ``virtlogd-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 +``unix_sock_dir`` setting in ``virtlogd.conf`` must be changed in +lock-step with the equivalent setting in the unit files to ensure that +``virtlogd`` can identify the sockets. + +Locking daemon +============== + +The ``virtlockd`` daemon provides a service for holding locks against file +images and devices serving as backing storage for virtual disks. The locks +will be held for as long as there is a QEMU process running with the disk +open. + +To ensure continuity of locking, the daemon holds open anoymous 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`` + +Locking Sockets +--------------- + +When running in system mode, ``virtlockd`` exposes two UNIX domain sockets: + +* ``/var/run/libvirt/virtlockd-sock`` - the primary socket for accessing + libvirt APIs, with full read-write privileges. Access to the socket is + restricted to the root user. + +* ``/var/run/libvirt/virtlockd-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, ``virtlockd`` exposes two UNIX domain sockets + +* ``$XDG_RUNTIME_DIR/libvirt/virtlockd-sock`` - the primary socket for + accessing libvirt APIs, with full read-write privileges. Access to the + socket is restricted to the unprivileged user running the daemon. + +* ``$XDG_RUNTIME_DIR/libvirt/virtlockd-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. + +``$XDG_RUNTIME_DIR`` commonly points to a per-user private location on tmpfs, +such as ``/run/user/$UID``. + +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 + typically only needed to control the use of the auto shutdown timeout value. + +* ``virtlockd.socket`` - the unit file corresponding to the main read-write + UNIX socket ``/var/run/libvirt/virtlockd-sock``. This socket is recommended + to be started on boot by default. + +* ``virtlockd-admin.socket`` - the unit file corresponding to the administrative + UNIX socket ``/var/run/libvirt/virtlockd-admin-sock``. This socket is + recommended to be started on boot by default. + +When systemd socket activation is used a number of configuration settings in +``virtlockd.conf`` are no longer honoured. Instead these settings must be +controlled via the system unit files + +* ``unix_sock_group`` - UNIX socket group owner, controlled via the + ``SocketGroup`` parameter in the ``virtlockd.socket`` and + ``virtlockd-ro.socket`` unit files + +* ``unix_sock_ro_perms`` - read-only UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virtlockd-ro.socket`` unit file + +* ``unix_sock_rw_perms`` - read-write UNIX socket permissions, controlled via + the ``SocketMode`` parameter in the ``virtlockd.socket`` unit file + +* ``unix_sock_admin_perms`` - admin UNIX socket permissions, controlled via the + ``SocketMode`` parameter in the ``virtlockd-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 + ``virtlockd.socket`` and ``virtlockd-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 +``unix_sock_dir`` setting in ``virtlockd.conf`` must be changed in +lock-step with the equivalent setting in the unit files to ensure that +``virtlockd`` can identify the sockets. diff --git a/docs/docs.html.in b/docs/docs.html.in index 004f099a9f..142c79bfa9 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -18,6 +18,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.24.1