From 84fe15c332f3ad2852d67bd088c91e847b34a6e5 Mon Sep 17 00:00:00 2001 From: "Daniel P. Berrange" Date: Fri, 29 Nov 2013 16:23:42 +0000 Subject: [PATCH] Add docs about audit subsystem logging 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. Signed-off-by: Daniel P. Berrange --- 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 0000000000..c827ab9a74 --- /dev/null +++ b/docs/auditlog.html.in @@ -0,0 +1,321 @@ + + + + +

Audit log

+ + + +

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 +

+ + + +

+ 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/libivrtd.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 interace 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 charecter 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
+
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
+
+ + +

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
+
+ + + diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index d821a9e818..60daf153fb 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -90,6 +90,10 @@ Logging The library and the daemon logging support +
  • + Audit log + Audit trail logs for host operations +
  • Firewall Firewall and network filter configuration