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