5:43 a.m.
Signed-off-by: Erik Skultety <eskultet(a)redhat.com>
---
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