Re: [PATCH] Add docs about audit subsystem logging

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Fri, Nov 29, 2013 at 04:23:42PM +0000, Daniel P. Berrange wrote:
> From: "Daniel P. Berrange" <berrange@xxxxxxxxxx>
> 
> Adds a new page to the website "Deployment" section describing
> what data is sent to the audit logs and how to configure libvirtd
> audit settings.

  ACK, pushed !

Daniel

> Signed-off-by: Daniel P. Berrange <berrange@xxxxxxxxxx>
> ---
>  docs/auditlog.html.in | 321 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  docs/sitemap.html.in  |   4 +
>  2 files changed, 325 insertions(+)
>  create mode 100644 docs/auditlog.html.in
> 
> diff --git a/docs/auditlog.html.in b/docs/auditlog.html.in
> new file mode 100644
> index 0000000..c827ab9
> --- /dev/null
> +++ b/docs/auditlog.html.in
> @@ -0,0 +1,321 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
> +<html xmlns="http://www.w3.org/1999/xhtml";>
> +  <body>
> +    <h1>Audit log</h1>
> +
> +    <ul id="toc"></ul>
> +
> +    <h2><a name="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 name="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/libivrtd.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 name="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>pid</dt>
> +      <dd>Process ID of the libvirtd daemon generating the audit record.</dd>
> +      <dt>uid</dt>
> +      <dd>User ID of the libvirtd daemon process generating the audit record.</dd>
> +      <dt>subj</dt>
> +      <dd>Security context of the libvirtd daemon process generating the audit record.</dd>
> +      <dt>msg</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>virt</dt>
> +      <dd>Type of virtualization driver used. One of <code>qemu</code> or <code>lxc</code></dd>
> +      <dt>vm</dt>
> +      <dd>Host driver unique name of the guest</dd>
> +      <dt>uuid</dt>
> +      <dd>Globally unique identifier for the guest</dd>
> +      <dt>exe</dt>
> +      <dd>Path of the libvirtd daemon</dd>
> +      <dt>hostname</dt>
> +      <dd>Currently unused</dd>
> +      <dt>addr</dt>
> +      <dd>Currently unused</dd>
> +      <dt>terminal</dt>
> +      <dd>Currently unused</dd>
> +      <dt>res</dt>
> +      <dd>Result of the action, either <code>success</code> or <code>failed</code></dd>
> +    </dl>
> +
> +    <h3><a name="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>op</dt>
> +      <dd>Type of operation performed. One of <code>start</code>, <code>stop</code> or <code>init</code></dd>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the operation to happen</dd>
> +      <dt>vm-pid</dt>
> +      <dd>ID of the primary/leading process associated with the guest</dd>
> +      <dt>init-pid</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>pid-ns</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 name="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>model</dt>
> +      <dd>The security driver type. One of <code>selinux</code> or <code>apparmor</code></dd>
> +      <dt>vm-ctx</dt>
> +      <dd>Security context for the guest process</dd>
> +      <dt>img-ctx</dt>
> +      <dd>Security context for the guest disk images and other assigned host resources</dd>
> +    </dl>
> +
> +    <h3><a name="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 name="typeresourcevcpu">Virtual CPU</a></h4>
> +
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>vcpu</code></dd>
> +      <dt>old-vcpu</dt>
> +      <dd>Original vCPU count, or 0</dd>
> +      <dt>new-vcpu</dt>
> +      <dd>Updated vCPU count</dd>
> +    </dl>
> +
> +
> +    <h4><a name="typeresourcemem">Memory</a></h4>
> +
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>mem</code></dd>
> +      <dt>old-mem</dt>
> +      <dd>Original memory size in bytes, or 0</dd>
> +      <dt>new-mem</dt>
> +      <dd>Updated memory size in bytes</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcedisk">Disk</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>disk</code></dd>
> +      <dt>old-disk</dt>
> +      <dd>Original host file or device path acting as the disk backing file</dd>
> +      <dt>new-disk</dt>
> +      <dd>Updated host file or device path acting as the disk backing file</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcenic">Network interface</a></h4>
> +
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>net</code></dd>
> +      <dt>old-net</dt>
> +      <dd>Original MAC address of the guest network interface</dd>
> +      <dt>new-net</dt>
> +      <dd>Updated MAC address of the guest network interface</dd>
> +    </dl>
> +
> +    <p>
> +      If there is a host network interace associated with the guest NIC then
> +      further records may be generated
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>net</code></dd>
> +      <dt>net</dt>
> +      <dd>MAC address of the host network interface</dd>
> +      <dt>rdev</dt>
> +      <dd>Name of the host network interface</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcefs">Filesystem</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>fs</code></dd>
> +      <dt>old-fs</dt>
> +      <dd>Original host directory, file or device path backing the filesystem </dd>
> +      <dt>new-fs</dt>
> +      <dd>Updated host directory, file or device path backing the filesystem</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcehost">Host device</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>hostdev</code> or <code>dev</code></dd>
> +      <dt>dev</dt>
> +      <dd>The unique bus identifier of the USB, PCI or SCSI device, if <code>resrc=dev</code></dd>
> +      <dt>disk</dt>
> +      <dd>The path of the block device assigned to the guest, if <code>resrc=hostdev</code></dd>
> +      <dt>chardev</dt>
> +      <dd>The path of the charecter device assigned to the guest, if <code>resrc=hostdev</code></dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcetpm">TPM</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>tpm</code></dd>
> +      <dt>device</dt>
> +      <dd>The path of the host TPM device assigned to the guest</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcerng">RNG</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>rng</code></dd>
> +      <dt>old-rng</dt>
> +      <dd>Original path of the host entropy source for the RNG</dd>
> +      <dt>new-rng</dt>
> +      <dd>Updated path of the host entropy source for the RNG</dd>
> +    </dl>
> +
> +
> +    <h4><a name="typeresourceredir">Redirected device</a></h4>
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>redir</code></dd>
> +      <dt>bus</dt>
> +      <dd>The bus type, only <code>usb</code> allowed</dd>
> +      <dt>device</dt>
> +      <dd>The device type, only <code>USB redir</code> allowed</dd>
> +    </dl>
> +
> +    <h4><a name="typeresourcecgroup">Control group</a></h4>
> +
> +    <p>
> +      The <code>msg</code> field will include the following sub-fields
> +    </p>
> +
> +    <dl>
> +      <dt>reason</dt>
> +      <dd>The reason which caused the resource to be assigned to happen</dd>
> +      <dt>resrc</dt>
> +      <dd>The type of resource assigned. Set to <code>cgroup</code></dd>
> +      <dt>cgroup</dt>
> +      <dd>The name of the cgroup controller</dd>
> +    </dl>
> +
> +  </body>
> +</html>
> diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
> index d821a9e..60daf15 100644
> --- a/docs/sitemap.html.in
> +++ b/docs/sitemap.html.in
> @@ -91,6 +91,10 @@
>                  <span>The library and the daemon logging support</span>
>                </li>
>                <li>
> +                <a href="auditlog.html">Audit log</a>
> +                <span>Audit trail logs for host operations</span>
> +              </li>
> +              <li>
>                  <a href="firewall.html">Firewall</a>
>                  <span>Firewall and network filter configuration</span>
>                </li>
> -- 
> 1.8.3.1
> 
> --
> libvir-list mailing list
> libvir-list@xxxxxxxxxx
> https://www.redhat.com/mailman/listinfo/libvir-list

-- 
Daniel Veillard      | Open Source and Standards, Red Hat
veillard@xxxxxxxxxx  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | virtualization library  http://libvirt.org/

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]