From f5ac2714e9b4b63b37bf634e1724853eb39643a0 Mon Sep 17 00:00:00 2001 From: Erik Skultety Date: Fri, 12 Mar 2021 12:04:40 +0100 Subject: [PATCH] docs: html.in: Convert auditlog to rst Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- 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 @@ - - - - -

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 -

    - -
      -
    • 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/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 b61377ea8b..4f922864fe 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -33,7 +33,6 @@ docs_assets = [ docs_html_in_files = [ '404', 'architecture', - 'auditlog', 'auth', 'bindings', 'bugs', @@ -107,6 +106,7 @@ docs_rst_files = [ 'api_extension', 'api', 'apps', + 'auditlog', 'best-practices', 'ci', 'coding-style',