Signed-off-by: Erik Skultety <eskultet@xxxxxxxxxx> --- docs/auditlog.html.in | 375 ------------------------------------------ docs/auditlog.rst | 321 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 322 insertions(+), 376 deletions(-) delete mode 100644 docs/auditlog.html.in create mode 100644 docs/auditlog.rst diff --git a/docs/auditlog.html.in b/docs/auditlog.html.in deleted file mode 100644 index eb00d9742e..0000000000 --- a/docs/auditlog.html.in +++ /dev/null @@ -1,375 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Audit log</h1> - - <ul id="toc"></ul> - - <h2><a id="intro">Introduction</a></h2> - - <p> - A number of the libvirt virtualization drivers (QEMU/KVM and LXC) include - support for logging details of important operations to the host's audit - subsystem. This provides administrators / auditors with a canonical historical - record of changes to virtual machines' / containers' lifecycle states and - their configuration. On hosts which are running the Linux audit daemon, - the logs will usually end up in <code>/var/log/audit/audit.log</code> - </p> - - <h2><a id="config">Configuration</a></h2> - - <p> - The libvirt audit integration is enabled by default on any host which has - the Linux audit subsystem active, and disabled otherwise. It is possible - to alter this behaviour in the <code>/etc/libvirt/libvirtd.conf</code> - configuration file, via the <code>audit_level</code> parameter - </p> - - <ul> - <li><code>audit_level=0</code> - libvirt auditing is disabled regardless - of host audit subsystem enablement.</li> - <li><code>audit_level=1</code> - libvirt auditing is enabled if the host - audit subsystem is enabled, otherwise it is disabled. This is the - default behaviour.</li> - <li><code>audit_level=2</code> - libvirt auditing is enabled regardless - of host audit subsystem enablement. If the host audit subsystem is - disabled, then libvirtd will refuse to complete startup and exit with - an error.</li> - </ul> - - <p> - In addition to have formal messages sent to the audit subsystem it is - possible to tell libvirt to inject messages into its own logging - layer. This will result in messages ending up in the systemd journal - or <code>/var/log/libvirt/libvirtd.log</code> on non-systemd hosts. - This is disabled by default, but can be requested by setting the - <code>audit_logging=1</code> configuration parameter in the same file - mentioned above. - </p> - - <h2><a id="types">Message types</a></h2> - - <p> - Libvirt defines three core audit message types each of which will - be described below. There are a number of common fields that will - be reported for all message types. - </p> - - <dl> - <dt><code>pid</code></dt> - <dd>Process ID of the libvirtd daemon generating the audit record.</dd> - <dt><code>uid</code></dt> - <dd>User ID of the libvirtd daemon process generating the audit record.</dd> - <dt><code>subj</code></dt> - <dd>Security context of the libvirtd daemon process generating the audit record.</dd> - <dt><code>msg</code></dt> - <dd>String containing a list of key=value pairs specific to the type of audit record being reported.</dd> - </dl> - - <p> - Some fields in the <code>msg</code> string are common to audit records - </p> - - <dl> - <dt><code>virt</code></dt> - <dd>Type of virtualization driver used. One of <code>qemu</code> or <code>lxc</code></dd> - <dt><code>vm</code></dt> - <dd>Host driver unique name of the guest</dd> - <dt><code>uuid</code></dt> - <dd>Globally unique identifier for the guest</dd> - <dt><code>exe</code></dt> - <dd>Path of the libvirtd daemon</dd> - <dt><code>hostname</code></dt> - <dd>Currently unused</dd> - <dt><code>addr</code></dt> - <dd>Currently unused</dd> - <dt><code>terminal</code></dt> - <dd>Currently unused</dd> - <dt><code>res</code></dt> - <dd>Result of the action, either <code>success</code> or <code>failed</code></dd> - </dl> - - <h3><a id="typecontrol">VIRT_CONTROL</a></h3> - - <p> - Reports change in the lifecycle state of a virtual machine. The <code>msg</code> - field will include the following sub-fields - </p> - - <dl> - <dt><code>op</code></dt> - <dd>Type of operation performed. One of <code>start</code>, <code>stop</code> or <code>init</code></dd> - <dt><code>reason</code></dt> - <dd>The reason which caused the operation to happen</dd> - <dt><code>vm-pid</code></dt> - <dd>ID of the primary/leading process associated with the guest</dd> - <dt><code>init-pid</code></dt> - <dd>ID of the <code>init</code> process in a container. Only if <code>op=init</code> and <code>virt=lxc</code></dd> - <dt><code>pid-ns</code></dt> - <dd>Namespace ID of the <code>init</code> process in a container. Only if <code>op=init</code> and <code>virt=lxc</code></dd> - </dl> - - <h3><a id="typemachine">VIRT_MACHINE_ID</a></h3> - - <p> - Reports the association of a security context with a guest. The <code>msg</code> - field will include the following sub-fields - </p> - - <dl> - <dt><code>model</code></dt> - <dd>The security driver type. One of <code>selinux</code> or <code>apparmor</code></dd> - <dt><code>vm-ctx</code></dt> - <dd>Security context for the guest process</dd> - <dt><code>img-ctx</code></dt> - <dd>Security context for the guest disk images and other assigned host resources</dd> - </dl> - - <h3><a id="typeresource">VIRT_RESOURCE</a></h3> - - <p> - Reports the usage of a host resource by a guest. The fields include will - vary according to the type of device being reported. When the guest is - initially booted records will be generated for all assigned resources. - If any changes are made to the running guest configuration, for example - hotplug devices, or adjust resources allocation, further records will - be generated. - </p> - - <h4><a id="typeresourcevcpu">Virtual CPU</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>vcpu</code></dd> - <dt><code>old-vcpu</code></dt> - <dd>Original vCPU count, or 0</dd> - <dt><code>new-vcpu</code></dt> - <dd>Updated vCPU count</dd> - </dl> - - - <h4><a id="typeresourcemem">Memory</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>mem</code></dd> - <dt><code>old-mem</code></dt> - <dd>Original memory size in bytes, or 0</dd> - <dt><code>new-mem</code></dt> - <dd>Updated memory size in bytes</dd> - </dl> - - <h4><a id="typeresourcedisk">Disk</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>disk</code></dd> - <dt><code>old-disk</code></dt> - <dd>Original host file or device path acting as the disk backing file</dd> - <dt><code>new-disk</code></dt> - <dd>Updated host file or device path acting as the disk backing file</dd> - </dl> - - <h4><a id="typeresourcenic">Network interface</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>net</code></dd> - <dt><code>old-net</code></dt> - <dd>Original MAC address of the guest network interface</dd> - <dt><code>new-net</code></dt> - <dd>Updated MAC address of the guest network interface</dd> - </dl> - - <p> - If there is a host network interface associated with the guest NIC then - further records may be generated - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>net</code></dd> - <dt><code>net</code></dt> - <dd>MAC address of the host network interface</dd> - <dt><code>rdev</code></dt> - <dd>Name of the host network interface</dd> - </dl> - - <h4><a id="typeresourcefs">Filesystem</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>fs</code></dd> - <dt><code>old-fs</code></dt> - <dd>Original host directory, file or device path backing the filesystem </dd> - <dt><code>new-fs</code></dt> - <dd>Updated host directory, file or device path backing the filesystem</dd> - </dl> - - <h4><a id="typeresourcehost">Host device</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>hostdev</code> or <code>dev</code></dd> - <dt><code>dev</code></dt> - <dd>The unique bus identifier of the USB, PCI or SCSI device, if <code>resrc=dev</code></dd> - <dt><code>disk</code></dt> - <dd>The path of the block device assigned to the guest, if <code>resrc=hostdev</code></dd> - <dt><code>chardev</code></dt> - <dd>The path of the character device assigned to the guest, if <code>resrc=hostdev</code></dd> - </dl> - - <h4><a id="typeresourcetpm">TPM</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>tpm</code> or <code>tpm-emulator</code></dd> - <dt><code>device</code></dt> - <dd>The path of the host TPM device assigned to the guest</dd> - </dl> - - <h4><a id="typeresourcerng">RNG</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>rng</code></dd> - <dt><code>old-rng</code></dt> - <dd>Original path of the host entropy source for the RNG</dd> - <dt><code>new-rng</code></dt> - <dd>Updated path of the host entropy source for the RNG</dd> - </dl> - - <h4><a id="typeresourcechardev">console/serial/parallel/channel</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>chardev</code></dd> - <dt><code>old-chardev</code></dt> - <dd>Original path of the backing character device for given emulated device</dd> - <dt><code>new-chardev</code></dt> - <dd>Updated path of the backing character device for given emulated device</dd> - </dl> - - <h4><a id="typeresourcesmartcard">smartcard</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>smartcard</code></dd> - <dt><code>old-smartcard</code></dt> - <dd>Original path of the backing character device, certificate store or - "nss-smartcard-device" for host smartcard passthrough. - </dd> - <dt><code>new-smartcard</code></dt> - <dd>Updated path of the backing character device, certificate store or - "nss-smartcard-device" for host smartcard passthrough. - </dd> - </dl> - - <h4><a id="typeresourceredir">Redirected device</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>redir</code></dd> - <dt><code>bus</code></dt> - <dd>The bus type, only <code>usb</code> allowed</dd> - <dt><code>device</code></dt> - <dd>The device type, only <code>USB redir</code> allowed</dd> - </dl> - - <h4><a id="typeresourcecgroup">Control group</a></h4> - - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>cgroup</code></dd> - <dt><code>cgroup</code></dt> - <dd>The name of the cgroup controller</dd> - </dl> - - - <h4><a id="typeresourceshmem">Shared memory</a></h4> - <p> - The <code>msg</code> field will include the following sub-fields - </p> - - <dl> - <dt><code>resrc</code></dt> - <dd>The type of resource assigned. Set to <code>shmem</code></dd> - <dt><code>reason</code></dt> - <dd>The reason which caused the resource to be assigned to happen</dd> - <dt><code>size</code></dt> - <dd>The size of the shared memory region</dd> - <dt><code>shmem</code></dt> - <dd>Name of the shared memory region</dd> - <dt><code>source</code></dt> - <dd>Path of the backing character device for given emulated device</dd> - </dl> - - </body> -</html> diff --git a/docs/auditlog.rst b/docs/auditlog.rst new file mode 100644 index 0000000000..e99374ffa8 --- /dev/null +++ b/docs/auditlog.rst @@ -0,0 +1,321 @@ +========= +Audit log +========= + +.. contents:: + +Introduction +------------ + +A number of the libvirt virtualization drivers (QEMU/KVM and LXC) +include support for logging details of important operations to the +host's audit subsystem. This provides administrators / auditors with a +canonical historical record of changes to virtual machines' / +containers' lifecycle states and their configuration. On hosts which are +running the Linux audit daemon, the logs will usually end up in +``/var/log/audit/audit.log`` + +Configuration +------------- + +The libvirt audit integration is enabled by default on any host which +has the Linux audit subsystem active, and disabled otherwise. It is +possible to alter this behaviour in the ``/etc/libvirt/libvirtd.conf`` +configuration file, via the ``audit_level`` parameter + +- ``audit_level=0`` - libvirt auditing is disabled regardless of host + audit subsystem enablement. +- ``audit_level=1`` - libvirt auditing is enabled if the host audit + subsystem is enabled, otherwise it is disabled. This is the default + behaviour. +- ``audit_level=2`` - libvirt auditing is enabled regardless of host + audit subsystem enablement. If the host audit subsystem is disabled, + then libvirtd will refuse to complete startup and exit with an error. + +In addition to have formal messages sent to the audit subsystem it is +possible to tell libvirt to inject messages into its own logging layer. +This will result in messages ending up in the systemd journal or +``/var/log/libvirt/libvirtd.log`` on non-systemd hosts. This is disabled +by default, but can be requested by setting the ``audit_logging=1`` +configuration parameter in the same file mentioned above. + +Message types +------------- + +Libvirt defines three core audit message types each of which will be +described below. There are a number of common fields that will be +reported for all message types. + +``pid`` + Process ID of the libvirtd daemon generating the audit record. +``uid`` + User ID of the libvirtd daemon process generating the audit record. +``subj`` + Security context of the libvirtd daemon process generating the audit + record. +``msg`` + String containing a list of key=value pairs specific to the type of + audit record being reported. + +Some fields in the ``msg`` string are common to audit records + +``virt`` + Type of virtualization driver used. One of ``qemu`` or ``lxc`` +``vm`` + Host driver unique name of the guest +``uuid`` + Globally unique identifier for the guest +``exe`` + Path of the libvirtd daemon +``hostname`` + Currently unused +``addr`` + Currently unused +``terminal`` + Currently unused +``res`` + Result of the action, either ``success`` or ``failed`` + +VIRT_CONTROL +~~~~~~~~~~~~ + +Reports change in the lifecycle state of a virtual machine. The ``msg`` +field will include the following sub-fields + +``op`` + Type of operation performed. One of ``start``, ``stop`` or ``init`` +``reason`` + The reason which caused the operation to happen +``vm-pid`` + ID of the primary/leading process associated with the guest +``init-pid`` + ID of the ``init`` process in a container. Only if ``op=init`` and + ``virt=lxc`` +``pid-ns`` + Namespace ID of the ``init`` process in a container. Only if + ``op=init`` and ``virt=lxc`` + +VIRT_MACHINE_ID +~~~~~~~~~~~~~~~ + +Reports the association of a security context with a guest. The ``msg`` +field will include the following sub-fields + +``model`` + The security driver type. One of ``selinux`` or ``apparmor`` +``vm-ctx`` + Security context for the guest process +``img-ctx`` + Security context for the guest disk images and other assigned host + resources + +VIRT_RESOURCE +~~~~~~~~~~~~~ + +Reports the usage of a host resource by a guest. The fields include will +vary according to the type of device being reported. When the guest is +initially booted records will be generated for all assigned resources. +If any changes are made to the running guest configuration, for example +hotplug devices, or adjust resources allocation, further records will be +generated. + +Virtual CPU +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``vcpu`` +``old-vcpu`` + Original vCPU count, or 0 +``new-vcpu`` + Updated vCPU count + +Memory +^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``mem`` +``old-mem`` + Original memory size in bytes, or 0 +``new-mem`` + Updated memory size in bytes + +Disk +^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``disk`` +``old-disk`` + Original host file or device path acting as the disk backing file +``new-disk`` + Updated host file or device path acting as the disk backing file + +Network interface +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``old-net`` + Original MAC address of the guest network interface +``new-net`` + Updated MAC address of the guest network interface + +If there is a host network interface associated with the guest NIC then +further records may be generated + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``net`` + MAC address of the host network interface +``rdev`` + Name of the host network interface + +Filesystem +^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``fs`` +``old-fs`` + Original host directory, file or device path backing the filesystem +``new-fs`` + Updated host directory, file or device path backing the filesystem + +Host device +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``hostdev`` or ``dev`` +``dev`` + The unique bus identifier of the USB, PCI or SCSI device, if + ``resrc=dev`` +``disk`` + The path of the block device assigned to the guest, if + ``resrc=hostdev`` +``chardev`` + The path of the character device assigned to the guest, if + ``resrc=hostdev`` + +TPM +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``tpm`` or ``tpm-emulator`` +``device`` + The path of the host TPM device assigned to the guest + +RNG +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``rng`` +``old-rng`` + Original path of the host entropy source for the RNG +``new-rng`` + Updated path of the host entropy source for the RNG + +console/serial/parallel/channel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``chardev`` +``old-chardev`` + Original path of the backing character device for given emulated + device +``new-chardev`` + Updated path of the backing character device for given emulated + device + +smartcard +^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``smartcard`` +``old-smartcard`` + Original path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. +``new-smartcard`` + Updated path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. + +Redirected device +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``redir`` +``bus`` + The bus type, only ``usb`` allowed +``device`` + The device type, only ``USB redir`` allowed + +Control group +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``cgroup`` +``cgroup`` + The name of the cgroup controller + +Shared memory +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``resrc`` + The type of resource assigned. Set to ``shmem`` +``reason`` + The reason which caused the resource to be assigned to happen +``size`` + The size of the shared memory region +``shmem`` + Name of the shared memory region +``source`` + Path of the backing character device for given emulated device diff --git a/docs/meson.build b/docs/meson.build index 0e0c266cb9..f80a08112e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'auditlog', 'auth', 'bindings', 'bugs', @@ -107,6 +106,7 @@ docs_rst_files = [ 'api', 'apps', 'architecture', + 'auditlog', 'best-practices', 'ci', 'coding-style', -- 2.29.2
