From nobody Sat May 4 14:34:35 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1616178870; cv=none; d=zohomail.com; s=zohoarc; b=IA0F84C1EyQIZLmexJ04yKsXxf+59oeto7GR4nT+9DRlvSOMeNCWcRnB2BzD+7g32Xw+NTKILzygCtTaQJdJb1qfUx78jSCtVSfQ9KqFVGf/pYDvQiDmkODtFHeZaB8ChE1g9nL0vxyEduwGJ0m7tA/UHcldLqyT20m8fM2i7tI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1616178870; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=HP/zCcBIP0Dnw1YksjJpw95b0ZpF8RiNN04IDSIG4bk=; b=GJE6rThbfQzPuPhSZLP+kmUcG6gXV/oqjHr0CV6mT3SK/s5rhJMhdm2LaDzRpEKQ8loUL83/tG1VwOsH71d7fj5v0dhcVmE7sIaq3IF/U1cRgLN90IFumhTsgfT9eUBlgqtd6kx+faBBQ45zZ8HNxHA+nXGIMW5/BqRNkQTlX2c= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1616178870802960.3829083115468; Fri, 19 Mar 2021 11:34:30 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-351-LC13Dg4OPACv-g9MCpn84Q-1; Fri, 19 Mar 2021 14:34:25 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5548E839A47; Fri, 19 Mar 2021 18:34:17 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2E94D5D9F2; Fri, 19 Mar 2021 18:34:17 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id E62181800662; Fri, 19 Mar 2021 18:34:16 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12JIY119024589 for ; Fri, 19 Mar 2021 14:34:01 -0400 Received: by smtp.corp.redhat.com (Postfix) id 73A995D9F2; Fri, 19 Mar 2021 18:34:01 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.33]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2DA555D9E3 for ; Fri, 19 Mar 2021 18:33:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616178869; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=HP/zCcBIP0Dnw1YksjJpw95b0ZpF8RiNN04IDSIG4bk=; b=UGEivBkOdtltlJyyerLbeD7teqVuJrOEarFG6wdru3P9YkRQPulW44pwAMS+ZlYXpdLuTo TzwHhETNGQPdYf53SusF4XnGho83CQL8+SA9B28CgK6XefTB63Km2a2hCXH85Zf2boWshR 0hCyZv6/tCNxXS2AYupTaXMpMZRQnuQ= X-MC-Unique: LC13Dg4OPACv-g9MCpn84Q-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 1/6] docs/drvqemu: Convert to RST Date: Fri, 19 Mar 2021 19:33:49 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" There are two links to this document using anchors so they need to be updated as well. Signed-off-by: Peter Krempa Reviewed-by: Martin Kletzander --- docs/drvqemu.html.in | 743 -------------------------------- docs/drvqemu.rst | 588 +++++++++++++++++++++++++ docs/formatdomain.rst | 2 +- docs/manpages/virt-qemu-run.rst | 2 +- docs/meson.build | 2 +- 5 files changed, 591 insertions(+), 746 deletions(-) delete mode 100644 docs/drvqemu.html.in create mode 100644 docs/drvqemu.rst diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in deleted file mode 100644 index fdf74979ad..0000000000 --- a/docs/drvqemu.html.in +++ /dev/null @@ -1,743 +0,0 @@ - - - - -

KVM/QEMU hypervisor driver

- -
    - -

    - The libvirt KVM/QEMU driver can manage any QEMU emulator from - version 1.5.0 or later. -

    - -

    Project Links

    - -
      -
    • - The KVM Linux - hypervisor -
      • -
    • - The QEMU emulator -
      • -
    - -

    Deployment pre-requisites

    - -
      -
    • - QEMU emulators: The driver will probe /usr/= bin - for the presence of qemu, qemu-system-x86_64, - qemu-system-microblaze, - qemu-system-microblazeel, - qemu-system-mips,qemu-system-mipsel, - qemu-system-sparc,qemu-system-ppc. The r= esults - of this can be seen from the capabilities XML output. -
      • -
    • - KVM hypervisor: The driver will probe /usr/= bin - for the presence of qemu-kvm and /dev/kvm device - node. If both are found, then KVM fully virtualized, hardware acce= lerated - guests will be available. -
      • -
    - -

    Connections to QEMU driver

    - -

    - The libvirt QEMU driver is a multi-instance driver, providing a single - system wide privileged driver (the "system" instance), and per-user - unprivileged drivers (the "session" instance). The URI driver protocol - is "qemu". Some example connection URIs for the libvirt driver are: -

    - -
    -qemu:///session                      (local access to per-user instance)
-qemu+unix:///session                 (local access to per-user instance)
-
-qemu:///system                       (local access to system instance)
-qemu+unix:///system                  (local access to system instance)
-qemu://example.com/system            (remote access, TLS/x509)
-qemu+tcp://example.com/system        (remote access, SASl/Kerberos)
-qemu+ssh://root@example.com/system   (remote access, SSH tunnelled)
-
    - -

    Embedded driver

    - -

    - Since 6.1.0 the QEMU driver has experimental support for operating - in an embedded mode. In this scenario, rather than connecting to - the libvirtd daemon, the QEMU driver runs in the client application - process directly. To use this the client application must have - registered & be running an instance of the event loop. To open - the driver in embedded mode the app use the new URI path and specify - a virtual root directory under which the driver will create content. - The path to the root directory must be absolute. Passing a relative - path results in an error. -

    - - 
    -      qemu:///embed?root=3D/some/dir
-
    - -

    - Broadly speaking the range of functionality is intended to be - on a par with that seen when using the traditional system or - session libvirt connections to QEMU. The features will of course - differ depending on whether the application using the embedded - driver is running privileged or unprivileged. For example PCI - device assignment or TAP based networking are only available - when running privileged. While the embedded mode is still classed - as experimental some features may change their default settings - between releases. -

    - -

    - By default if the application uses any APIs associated with - secondary drivers, these will result in a connection being - opened to the corresponding driver in libvirtd. For example, - this allows a virtual machine from the embedded QEMU to connect - its NIC to a virtual network or connect its disk to a storage - volume. Some of the secondary drivers will also be able to support - running in embedded mode. Currently this is supported by the - secrets driver, to allow for use of VMs with encrypted disks -

    - -

    Directory tree

    - -

    - Under the specified root directory the following locations will - be used -

    - - 
    -/some/dir
-  |
-  +- log
-  |   |
-  |   +- qemu
-  |   +- swtpm
-  |
-  +- etc
-  |   |
-  |   +- qemu
-  |   +- pki
-  |       |
-  |       +- qemu
-  |
-  +- run
-  |   |
-  |   +- qemu
-  |   +- swtpm
-  |
-  +- cache
-  |   |
-  |   +- qemu
-  |
-  +- lib
-      |
-      +- qemu
-      +- swtpm
-
    - -

    - Note that UNIX domain sockets used for QEMU virtual machines had - a maximum filename length of 108 characters. Bear this in mind - when picking a root directory to avoid risk of exhausting the - filename space. The application is responsible for recursively - purging the contents of this directory tree once they no longer - require a connection, though it can also be left intact for reuse - when opening a future connection. -

    - -

    API usage with event loop

    - -

    - To use the QEMU driver in embedded mode the application must - register an event loop with libvirt. Many of the QEMU driver - API calls will rely on the event loop processing data. With this - in mind, applications must NEVER invoke API - calls from the event loop thread itself, only other threads. - Not following this rule will lead to deadlocks in the API. - This restriction was lifted starting from 6.2.0 release, when - QMP processing moved to a dedicated thread. However, it is - important to let the event loop run after each API call, even - the ones made from the event loop thread itself. -

    - -

    Location of configuration files

    - -

    - The QEMU driver comes with sane default values. However, during its - initialization it reads a configuration file which offers system - administrator or an user to override some of that default. The locat= ion - of the file depends on the connection URI, as follows: -

    - - - - - - - - - - - - - - -
    qemu:///system/etc/libvirt/qemu.conf
    qemu:///session$XDG_CONFIG_HOME/libvirt/qemu.conf
    qemu:///embed$rootdir/etc/qemu.conf
    - -

    - If $XDG_CONFIG_HOME is not set in the environment, it - defaults to $HOME/.config. For the embed URI the - $rootdir represents the specified root directory from - the connection URI. -

    - -

    - Please note, that it is very likely that the only qemu.conf file that - will exist after installing libvirt is the - /etc/libvirt/qemu.conf, if users of the session daemon = or - the embed driver want to override a built in value, then they need to - create the file before connecting to the respective URI. -

    - -

    Driver security architecture

    - -

    - There are multiple layers to security in the QEMU driver, allowing f= or - flexibility in the use of QEMU based virtual machines. -

    - -

    Driver instances

    - -

    - As explained above there are two ways to access the QEMU driver - in libvirt. The "qemu:///session" family of URIs connect to a - libvirtd instance running as the same user/group ID as the client - application. Thus the QEMU instances spawned from this driver will - share the same privileges as the client application. The intended - use case for this driver is desktop virtualization, with virtual - machines storing their disk images in the user's home directory and - being managed from the local desktop login session. -

    - -

    - The "qemu:///system" family of URIs connect to a - libvirtd instance running as the privileged system account 'root'. - Thus the QEMU instances spawned from this driver may have much - higher privileges than the client application managing them. - The intended use case for this driver is server virtualization, - where the virtual machines may need to be connected to host - resources (block, PCI, USB, network devices) whose access requires - elevated privileges. -

    - -

    POSIX users/groups

    - -

    - In the "session" instance, the POSIX users/groups model restricts QE= MU - virtual machines (and libvirtd in general) to only have access to re= sources - with the same user/group ID as the client application. There is no - finer level of configuration possible for the "session" instances. -

    - -

    - In the "system" instance, libvirt releases from 0.7.0 onwards allow - control over the user/group that the QEMU virtual machines are run - as. A build of libvirt with no configuration parameters set will - still run QEMU processes as root:root. It is possible to change - this default by using the --with-qemu-user=3D$USERNAME and - --with-qemu-group=3D$GROUPNAME arguments to 'configure' during - build. It is strongly recommended that vendors build with both - of these arguments set to 'qemu'. Regardless of this build time - default, administrators can set a per-host default setting in - the /etc/libvirt/qemu.conf configuration file via - the user=3D$USERNAME and group=3D$GROUPNAME - parameters. When a non-root user or group is configured, the - libvirt QEMU driver will change uid/gid to match immediately - before executing the QEMU binary for a virtual machine. -

    - -

    - If QEMU virtual machines from the "system" instance are being - run as non-root, there will be greater restrictions on what - host resources the QEMU process will be able to access. The - libvirtd daemon will attempt to manage permissions on resources - to minimise the likelihood of unintentional security denials, - but the administrator / application developer must be aware of - some of the consequences / restrictions. -

    - -
      -
    • -

      - The directories /var/run/libvirt/qemu/, - /var/lib/libvirt/qemu/ and - /var/cache/libvirt/qemu/ must all have their - ownership set to match the user / group ID that QEMU - guests will be run as. If the vendor has set a non-root - user/group for the QEMU driver at build time, the - permissions should be set automatically at install time. - If a host administrator customizes user/group in - /etc/libvirt/qemu.conf, they will need to - manually set the ownership on these directories. -

      -
      • -
    • -

      - When attaching USB and PCI devices to a QEMU guest, - QEMU will need to access files in /dev/bus/usb - and /sys/bus/pci/devices respectively. The libvirtd= daemon - will automatically set the ownership on specific devices - that are assigned to a guest at start time. There should - not be any need for administrator changes in this respect. -

      -
      • -
    • -

      - Any files/devices used as guest disk images must be - accessible to the user/group ID that QEMU guests are - configured to run as. The libvirtd daemon will automatically - set the ownership of the file/device path to the correct - user/group ID. Applications / administrators must be aware - though that the parent directory permissions may still - deny access. The directories containing disk images - must either have their ownership set to match the user/group - configured for QEMU, or their UNIX file permissions must - have the 'execute/search' bit enabled for 'others'. -

      -

      - The simplest option is the latter one, of just enabling - the 'execute/search' bit. For any directory to be used - for storing disk images, this can be achieved by running - the following command on the directory itself, and any - parent directories -

      -
      -chmod o+x /path/to/directory
-
      -

      - In particular note that if using the "system" instance - and attempting to store disk images in a user home - directory, the default permissions on $HOME are typically - too restrictive to allow access. -

      -
      • -
    - -

    - The libvirt maintainers strongly recommend against - running QEMU as the root user/group. This should not be required - in most supported usage scenarios, as libvirt will generally do the - right thing to grant QEMU access to files it is permitted to - use when it is running non-root. -

    - -

    Linux process capabilities

    - -

    - In versions of libvirt prior to 6.0.0, even if QEMU was configured - to run as the root user / group, libvirt would strip all process - capabilities. This meant that QEMU could only read/write files - owned by root, or with open permissions. In reality, stripping - capabilities did not have any security benefit, as it was trivial - to get commands to run in another context with full capabilities, - for example, by creating a cronjob. -

    -

    - Thus since 6.0.0, if QEMU is running as root, it will keep all - process capabilities. Behaviour when QEMU is running non-root - is unchanged, it still has no capabilities. -

    - -

    SELinux basic confinement

    - -

    - The basic SELinux protection for QEMU virtual machines is intended to - protect the host OS from a compromised virtual machine process. There - is no protection between guests. -

    - -

    - In the basic model, all QEMU virtual machines run under the confined - domain root:system_r:qemu_t. It is required that any - disk image assigned to a QEMU virtual machine is labelled with - system_u:object_r:virt_image_t. In a default deployment, - package vendors/distributor will typically ensure that the directory - /var/lib/libvirt/images has this label, such that any - disk images created in this directory will automatically inherit the - correct labelling. If attempting to use disk images in another - location, the user/administrator must ensure the directory has be - given this requisite label. Likewise physical block devices must - be labelled system_u:object_r:virt_image_t. -

    -

    - Not all filesystems allow for labelling of individual files. In - particular NFS, VFat and NTFS have no support for labelling. In - these cases administrators must use the 'context' option when - mounting the filesystem to set the default label to - system_u:object_r:virt_image_t. In the case of - NFS, there is an alternative option, of enabling the virt_use_= nfs - SELinux boolean. -

    - -

    SELinux sVirt confinement

    - -

    - The SELinux sVirt protection for QEMU virtual machines builds to the - basic level of protection, to also allow individual guests to be - protected from each other. -

    - -

    - In the sVirt model, each QEMU virtual machine runs under its own - confined domain, which is based on system_u:system_r:svirt_t:s= 0 - with a unique category appended, eg, system_u:system_r:svirt_t= :s0:c34,c44. - The rules are setup such that a domain can only access files which a= re - labelled with the matching category level, eg - system_u:object_r:svirt_image_t:s0:c34,c44. This preven= ts one - QEMU process accessing any file resources that are prevent to anothe= r QEMU - process. -

    - -

    - There are two ways of assigning labels to virtual machines under sVi= rt. - In the default setup, if sVirt is enabled, guests will get an automa= tically - assigned unique label each time they are booted. The libvirtd daemon= will - also automatically relabel exclusive access disk images to match this - label. Disks that are marked as <shared> will get a generic - label system_u:system_r:svirt_image_t:s0 allowing all g= uests - read/write access them, while disks marked as <readonly> will - get a generic label system_u:system_r:svirt_content_t:s0 - which allows all guests read-only access. -

    - -

    - With statically assigned labels, the application should include the - desired guest and file labels in the XML at time of creating the - guest with libvirt. In this scenario the application is responsible - for ensuring the disk images & similar resources are suitably - labelled to match, libvirtd will not attempt any relabelling. -

    - -

    - If the sVirt security model is active, then the node capabilities - XML will include its details. If a virtual machine is currently - protected by the security model, then the guest XML will include - its assigned labels. If enabled at compile time, the sVirt security - model will always be activated if SELinux is available on the host - OS. To disable sVirt, and revert to the basic level of SELinux - protection (host protection only), the /etc/libvirt/qemu.conf<= /code> - file can be used to change the setting to security_driver=3D"n= one" -

    - -

    AppArmor sVirt confinement

    - -

    - When using basic AppArmor protection for the libvirtd daemon and - QEMU virtual machines, the intention is to protect the host OS - from a compromised virtual machine process. There is no protection - between guests. -

    - -

    - The AppArmor sVirt protection for QEMU virtual machines builds on - this basic level of protection, to also allow individual guests to - be protected from each other. -

    - -

    - In the sVirt model, if a profile is loaded for the libvirtd daemon, - then each qemu:///system QEMU virtual machine will have - a profile created for it when the virtual machine is started if one - does not already exist. This generated profile uses a profile name - based on the UUID of the QEMU virtual machine and contains rules - allowing access to only the files it needs to run, such as its disks, - pid file and log files. Just before the QEMU virtual machine is - started, the libvirtd daemon will change into this unique profile, - preventing the QEMU process from accessing any file resources that - are present in another QEMU process or the host machine. -

    - -

    - The AppArmor sVirt implementation is flexible in that it allows an - administrator to customize the template file in - /etc/apparmor.d/libvirt/TEMPLATE for site-specific - access for all newly created QEMU virtual machines. Also, when a new - profile is generated, two files are created: - /etc/apparmor.d/libvirt/libvirt-<uuid> and - /etc/apparmor.d/libvirt/libvirt-<uuid>.files. The - former can be fine-tuned by the administrator to allow custom access - for this particular QEMU virtual machine, and the latter will be - updated appropriately when required file access changes, such as when - a disk is added. This flexibility allows for situations such as - having one virtual machine in complain mode with all others in - enforce mode. -

    - -

    - While users can define their own AppArmor profile scheme, a typical - configuration will include a profile for /usr/sbin/libvirtd, - /usr/lib/libvirt/virt-aa-helper or - /usr/libexec/virt-aa-helper(a helper program which the - libvirtd daemon uses instead of manipulating AppArmor directly), and - an abstraction to be included by /etc/apparmor.d/libvirt/TEMPL= ATE - (typically /etc/apparmor.d/abstractions/libvirt-qemu). - An example profile scheme can be found in the examples/apparmor - directory of the source distribution. -

    - -

    - If the sVirt security model is active, then the node capabilities - XML will include its details. If a virtual machine is currently - protected by the security model, then the guest XML will include - its assigned profile name. If enabled at compile time, the sVirt - security model will be activated if AppArmor is available on the host - OS and a profile for the libvirtd daemon is loaded when libvirtd is - started. To disable sVirt, and revert to the basic level of AppArmor - protection (host protection only), the /etc/libvirt/qemu.conf<= /code> - file can be used to change the setting to security_driver=3D"n= one". -

    - - -

    Cgroups device ACLs

    - -

    - Linux kernels have a capability known as "cgroups" which is used - for resource management. It is implemented via a number of "controll= ers", - each controller covering a specific task/functional area. One of the - available controllers is the "devices" controller, which is able to - setup access control lists of block/character devices that a cgroup - should be allowed to access. If the "devices" controller is mounted = on a - host, then libvirt will automatically create a dedicated cgroup for = each - QEMU virtual machine and setup the device access control list so tha= t the - QEMU process can only access shared devices, and explicitly assigned= disks - images backed by block devices. -

    - -

    - The list of shared devices a guest is allowed access to is -

    - -
    -/dev/null, /dev/full, /dev/zero,
-/dev/random, /dev/urandom,
-/dev/ptmx, /dev/kvm,
-
    - -

    - In the event of unanticipated needs arising, this can be customized - via the /etc/libvirt/qemu.conf file. - To mount the cgroups device controller, the following command - should be run as root, prior to starting libvirtd -

    - -
    -mkdir /dev/cgroup
-mount -t cgroup none /dev/cgroup -o devices
-
    - -

    - libvirt will then place each virtual machine in a cgroup at - /dev/cgroup/libvirt/qemu/$VMNAME/ -

    - -

    Import and export of libvirt domain XML configs=

    - -

    The QEMU driver currently supports a single native - config format known as qemu-argv. The data for this for= mat - is expected to be a single line first a list of environment variable= s, - then the QEMu binary name, finally followed by the QEMU command line - arguments

    - -

    Converting from QEMU args to domain XML - -

    - Note: this operation is deleted as of - 5.5.0 and will return an error. -

    -

    - The virsh domxml-from-native provides a way to - convert an existing set of QEMU args into a guest description - using libvirt Domain XML that can then be used by libvirt. - Please note that this command is intended to be used to convert - existing qemu guests previously started from the command line to - be managed through libvirt. It should not be used a method of - creating new guests from scratch. New guests should be created - using an application calling the libvirt APIs (see - the libvirt applications page for some - examples) or by manually crafting XML to pass to virsh. -

    - -

    Converting from domain XML to QEMU args - -

    - The virsh domxml-to-native provides a way to convert a - guest description using libvirt Domain XML, into a set of QEMU args - that can be run manually. Note that currently the command line forma= tted - by libvirt is no longer suited for manually running qemu as the - configuration expects various resources and open file descriptors pa= ssed - to the process which are usually prepared by libvirtd. -

    - -

    Pass-through of arbitrary qemu - commands

    - -

    Libvirt provides an XML namespace and an optional - library libvirt-qemu.so for dealing specifically - with qemu. When used correctly, these extensions allow testing - specific qemu features that have not yet been ported to the - generic libvirt XML and API interfaces. However, they - are unsupported, in that the library is not guaranteed to - have a stable API, abusing the library or XML may result in - inconsistent state the crashes libvirtd, and upgrading either - qemu-kvm or libvirtd may break behavior of a domain that was - relying on a qemu-specific pass-through. If you find yourself - needing to use them to access a particular qemu feature, then - please post an RFE to the libvirt mailing list to get that - feature incorporated into the stable libvirt XML and API - interfaces. -

    -

    The library provides two - API: virDomainQemuMonitorCommand, for sending an - arbitrary monitor command (in either HMP or QMP format) to a - qemu guest (Since 0.8.3), - and virDomainQemuAttach, for registering a qemu - domain that was manually started so that it can then be managed - by libvirtd (Since 0.9.4, - removed as of 5.5.0). -

    -

    Additionally, the following XML additions allow fine-tuning of - the command line given to qemu when starting a domain - (Since 0.8.3). In order to use the - XML additions, it is necessary to issue an XML namespace request - (the special xmlns:name attribute) that - pulls in http://libvirt.org/schemas/domain/qemu/1.0; - typically, the namespace is given the name - of qemu. With the namespace in place, it is then - possible to add an element <qemu:commandline> - under domain, with the following sub-elements - repeated as often as needed: -

    -
    -
    qemu:arg
    -
    Add an additional command-line argument to the qemu - process when starting the domain, given by the value of the - attribute value. -
    -
    qemu:env
    -
    Add an additional environment variable to the qemu - process when starting the domain, given with the name-value - pair recorded in the attributes name - and optional value.
    -
    -

    Example:

    -<domain type=3D'qemu' xmlns:qemu=3D'http://libvirt.org/schemas/domain/q=
emu/1.0'>
-  <name>QEMU-fedora-i686</name>
-  <memory>219200</memory>
-  <os>
-    <type arch=3D'i686' machine=3D'pc'>hvm</type>
-  </os>
-  <devices>
-    <emulator>/usr/bin/qemu-system-x86_64</emulator>
-  </devices>
-  <qemu:commandline>
-    <qemu:arg value=3D'-newarg'/>
-    <qemu:env name=3D'QEMU_ENV' value=3D'VAL'/>
-  </qemu:commandline>
-</domain>
-
    - -

    QEMU feature configuration for testing=

    - -

    - In some cases e.g. when developing a new feature or for testing it= may - be required to control a given qemu feature (or qemu capability) t= o test - it before it's complete or disable it for debugging purposes. - Since 5.5.0 it's possible to use the = same - special qemu namespace as above - (http://libvirt.org/schemas/domain/qemu/1.0) and use - <qemu:capabilities> element to add - (<qemu:add capability=3D"capname"/>) or remove - (<qemu:del capability=3D"capname"/>) capability= bits. - The naming of the feature bits is the same libvirt uses in the sta= tus - XML. Note that this feature is meant for experiments only and shou= ld - _not_ be used in production. -

    - -

    Example:

    -<domain type=3D'qemu' xmlns:qemu=3D'http://libvirt.org/schemas/domain/q=
emu/1.0'>
-  <name>testvm</name>
-
-   [...]
-
-  <qemu:capabilities>
-    <qemu:add capability=3D'blockdev'/>
-    <qemu:del capability=3D'drive'/>
-  </qemu:capabilities>
-</domain>
-
    - -

    Example domain XML config

    - -

    QEMU emulated guest on x86_64

    - - 
    <domain type=3D'qemu'>
-  <name>QEMU-fedora-i686</name>
-  <uuid>c7a5fdbd-cdaf-9455-926a-d65c16db1809</uuid>
-  <memory>219200</memory>
-  <currentMemory>219200</currentMemory>
-  <vcpu>2</vcpu>
-  <os>
-    <type arch=3D'i686' machine=3D'pc'>hvm</type>
-    <boot dev=3D'cdrom'/>
-  </os>
-  <devices>
-    <emulator>/usr/bin/qemu-system-x86_64</emulator>
-    <disk type=3D'file' device=3D'cdrom'>
-      <source file=3D'/home/user/boot.iso'/>
-      <target dev=3D'hdc'/>
-      <readonly/>
-    </disk>
-    <disk type=3D'file' device=3D'disk'>
-      <source file=3D'/home/user/fedora.img'/>
-      <target dev=3D'hda'/>
-    </disk>
-    <interface type=3D'network'>
-      <source network=3D'default'/>
-    </interface>
-    <graphics type=3D'vnc' port=3D'-1'/>
-  </devices>
-</domain>
    - -

    KVM hardware accelerated guest on i686

    - - 
    <domain type=3D'kvm'>
-  <name>demo2</name>
-  <uuid>4dea24b3-1d52-d8f3-2516-782e98a23fa0</uuid>
-  <memory>131072</memory>
-  <vcpu>1</vcpu>
-  <os>
-    <type arch=3D"i686">hvm</type>
-  </os>
-  <clock sync=3D"localtime"/>
-  <devices>
-    <emulator>/usr/bin/qemu-kvm</emulator>
-    <disk type=3D'file' device=3D'disk'>
-      <source file=3D'/var/lib/libvirt/images/demo2.img'/>
-      <target dev=3D'hda'/>
-    </disk>
-    <interface type=3D'network'>
-      <source network=3D'default'/>
-      <mac address=3D'24:42:53:21:52:45'/>
-    </interface>
-    <graphics type=3D'vnc' port=3D'-1' keymap=3D'de'/>
-  </devices>
-</domain>
    - - - diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst new file mode 100644 index 0000000000..0f8fd9e47d --- /dev/null +++ b/docs/drvqemu.rst @@ -0,0 +1,588 @@ +.. role:: since +.. role:: removed + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +KVM/QEMU hypervisor driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + +The libvirt KVM/QEMU driver can manage any QEMU emulator from version 1.5.= 0 or +later. + +.. contents:: + +Project Links +------------- + +- The `KVM `__ Linux hypervisor +- The `QEMU `__ emulator + +Deployment pre-requisites +------------------------- + +- **QEMU emulators**: The driver will probe ``/usr/bin`` for the presence= of + ``qemu``, ``qemu-system-x86_64``, ``qemu-system-microblaze``, + ``qemu-system-microblazeel``, ``qemu-system-mips``,\ ``qemu-system-mips= el``, + ``qemu-system-sparc``,\ ``qemu-system-ppc``. The results of this can be= seen + from the capabilities XML output. +- **KVM hypervisor**: The driver will probe ``/usr/bin`` for the presence= of + ``qemu-kvm`` and ``/dev/kvm`` device node. If both are found, then KVM = fully + virtualized, hardware accelerated guests will be available. + +Connections to QEMU driver +-------------------------- + +The libvirt QEMU driver is a multi-instance driver, providing a single sys= tem +wide privileged driver (the "system" instance), and per-user unprivileged +drivers (the "session" instance). The URI driver protocol is "qemu". Some +example connection URIs for the libvirt driver are: + +:: + + qemu:///session (local access to per-user instance) + qemu+unix:///session (local access to per-user instance) + + qemu:///system (local access to system instance) + qemu+unix:///system (local access to system instance) + qemu://example.com/system (remote access, TLS/x509) + qemu+tcp://example.com/system (remote access, SASl/Kerberos) + qemu+ssh://root@example.com/system (remote access, SSH tunnelled) + +Embedded driver +~~~~~~~~~~~~~~~ + +Since 6.1.0 the QEMU driver has experimental support for operating in an +embedded mode. In this scenario, rather than connecting to the libvirtd da= emon, +the QEMU driver runs in the client application process directly. To use th= is the +client application must have registered & be running an instance of the ev= ent +loop. To open the driver in embedded mode the app use the new URI path and +specify a virtual root directory under which the driver will create conten= t. The +path to the root directory must be absolute. Passing a relative path resul= ts in +an error. + +:: + + qemu:///embed?root=3D/some/dir + +Broadly speaking the range of functionality is intended to be on a par wit= h that +seen when using the traditional system or session libvirt connections to Q= EMU. +The features will of course differ depending on whether the application us= ing +the embedded driver is running privileged or unprivileged. For example PCI +device assignment or TAP based networking are only available when running +privileged. While the embedded mode is still classed as experimental some +features may change their default settings between releases. + +By default if the application uses any APIs associated with secondary driv= ers, +these will result in a connection being opened to the corresponding driver= in +libvirtd. For example, this allows a virtual machine from the embedded QEM= U to +connect its NIC to a virtual network or connect its disk to a storage volu= me. +Some of the secondary drivers will also be able to support running in embe= dded +mode. Currently this is supported by the secrets driver, to allow for use = of VMs +with encrypted disks + +Directory tree +^^^^^^^^^^^^^^ + +Under the specified root directory the following locations will be used + +:: + + /some/dir + | + +- log + | | + | +- qemu + | +- swtpm + | + +- etc + | | + | +- qemu + | +- pki + | | + | +- qemu + | + +- run + | | + | +- qemu + | +- swtpm + | + +- cache + | | + | +- qemu + | + +- lib + | + +- qemu + +- swtpm + +Note that UNIX domain sockets used for QEMU virtual machines had a maximum +filename length of 108 characters. Bear this in mind when picking a root +directory to avoid risk of exhausting the filename space. The application = is +responsible for recursively purging the contents of this directory tree on= ce +they no longer require a connection, though it can also be left intact for= reuse +when opening a future connection. + +API usage with event loop +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use the QEMU driver in embedded mode the application must register an e= vent +loop with libvirt. Many of the QEMU driver API calls will rely on the even= t loop +processing data. With this in mind, applications must **NEVER** invoke API= calls +from the event loop thread itself, only other threads. Not following this = rule +will lead to deadlocks in the API. This restriction was lifted starting fr= om +6.2.0 release, when QMP processing moved to a dedicated thread. However, i= t is +important to let the event loop run after each API call, even the ones mad= e from +the event loop thread itself. + +Location of configuration files +------------------------------- + +The QEMU driver comes with sane default values. However, during its +initialization it reads a configuration file which offers system administr= ator +or an user to override some of that default. The location of the file depe= nds on +the connection URI, as follows: + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D +``qemu:///system`` ``/etc/libvirt/qemu.conf`` +``qemu:///session`` ``$XDG_CONFIG_HOME/libvirt/qemu.conf`` +``qemu:///embed`` ``$rootdir/etc/qemu.conf`` +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D + +If ``$XDG_CONFIG_HOME`` is not set in the environment, it defaults to +``$HOME/.config``. For the embed URI the ``$rootdir`` represents the speci= fied +root directory from the connection URI. + +Please note, that it is very likely that the only qemu.conf file that will= exist +after installing libvirt is the ``/etc/libvirt/qemu.conf``, if users of the +session daemon or the embed driver want to override a built in value, then= they +need to create the file before connecting to the respective URI. + +Driver security architecture +---------------------------- + +There are multiple layers to security in the QEMU driver, allowing for +flexibility in the use of QEMU based virtual machines. + +Driver instances +~~~~~~~~~~~~~~~~ + +As explained above there are two ways to access the QEMU driver in libvirt= . The +"qemu:///session" family of URIs connect to a libvirtd instance running as= the +same user/group ID as the client application. Thus the QEMU instances spaw= ned +from this driver will share the same privileges as the client application.= The +intended use case for this driver is desktop virtualization, with virtual +machines storing their disk images in the user's home directory and being +managed from the local desktop login session. + +The "qemu:///system" family of URIs connect to a libvirtd instance running= as +the privileged system account 'root'. Thus the QEMU instances spawned from= this +driver may have much higher privileges than the client application managing +them. The intended use case for this driver is server virtualization, wher= e the +virtual machines may need to be connected to host resources (block, PCI, U= SB, +network devices) whose access requires elevated privileges. + +POSIX users/groups +~~~~~~~~~~~~~~~~~~ + +In the "session" instance, the POSIX users/groups model restricts QEMU vir= tual +machines (and libvirtd in general) to only have access to resources with t= he +same user/group ID as the client application. There is no finer level of +configuration possible for the "session" instances. + +In the "system" instance, libvirt releases from 0.7.0 onwards allow contro= l over +the user/group that the QEMU virtual machines are run as. A build of libvi= rt +with no configuration parameters set will still run QEMU processes as root= :root. +It is possible to change this default by using the --with-qemu-user=3D$USE= RNAME +and --with-qemu-group=3D$GROUPNAME arguments to 'configure' during build. = It is +strongly recommended that vendors build with both of these arguments set to +'qemu'. Regardless of this build time default, administrators can set a pe= r-host +default setting in the ``/etc/libvirt/qemu.conf`` configuration file via t= he +``user=3D$USERNAME`` and ``group=3D$GROUPNAME`` parameters. When a non-roo= t user or +group is configured, the libvirt QEMU driver will change uid/gid to match +immediately before executing the QEMU binary for a virtual machine. + +If QEMU virtual machines from the "system" instance are being run as non-r= oot, +there will be greater restrictions on what host resources the QEMU process= will +be able to access. The libvirtd daemon will attempt to manage permissions = on +resources to minimise the likelihood of unintentional security denials, bu= t the +administrator / application developer must be aware of some of the consequ= ences +/ restrictions. + +- The directories ``/var/run/libvirt/qemu/``, ``/var/lib/libvirt/qemu/`` = and + ``/var/cache/libvirt/qemu/`` must all have their ownership set to match= the + user / group ID that QEMU guests will be run as. If the vendor has set a + non-root user/group for the QEMU driver at build time, the permissions = should + be set automatically at install time. If a host administrator customizes + user/group in ``/etc/libvirt/qemu.conf``, they will need to manually se= t the + ownership on these directories. + +- When attaching USB and PCI devices to a QEMU guest, QEMU will need to a= ccess + files in ``/dev/bus/usb`` and ``/sys/bus/pci/devices`` respectively. The + libvirtd daemon will automatically set the ownership on specific device= s that + are assigned to a guest at start time. There should not be any need for + administrator changes in this respect. + +- Any files/devices used as guest disk images must be accessible to the + user/group ID that QEMU guests are configured to run as. The libvirtd d= aemon + will automatically set the ownership of the file/device path to the cor= rect + user/group ID. Applications / administrators must be aware though that = the + parent directory permissions may still deny access. The directories + containing disk images must either have their ownership set to match the + user/group configured for QEMU, or their UNIX file permissions must hav= e the + 'execute/search' bit enabled for 'others'. + + The simplest option is the latter one, of just enabling the 'execute/se= arch' + bit. For any directory to be used for storing disk images, this can be + achieved by running the following command on the directory itself, and = any + parent directories + + :: + + chmod o+x /path/to/directory + + In particular note that if using the "system" instance and attempting to + store disk images in a user home directory, the default permissions on = $HOME + are typically too restrictive to allow access. + +The libvirt maintainers **strongly recommend against** running QEMU as the= root +user/group. This should not be required in most supported usage scenarios,= as +libvirt will generally do the right thing to grant QEMU access to files it= is +permitted to use when it is running non-root. + +Linux process capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In versions of libvirt prior to 6.0.0, even if QEMU was configured to run = as the +root user / group, libvirt would strip all process capabilities. This mean= t that +QEMU could only read/write files owned by root, or with open permissions. = In +reality, stripping capabilities did not have any security benefit, as it w= as +trivial to get commands to run in another context with full capabilities, = for +example, by creating a cronjob. + +Thus since 6.0.0, if QEMU is running as root, it will keep all process +capabilities. Behaviour when QEMU is running non-root is unchanged, it sti= ll has +no capabilities. + +SELinux basic confinement +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The basic SELinux protection for QEMU virtual machines is intended to prot= ect +the host OS from a compromised virtual machine process. There is no protec= tion +between guests. + +In the basic model, all QEMU virtual machines run under the confined domain +``root:system_r:qemu_t``. It is required that any disk image assigned to a= QEMU +virtual machine is labelled with ``system_u:object_r:virt_image_t``. In a +default deployment, package vendors/distributor will typically ensure that= the +directory ``/var/lib/libvirt/images`` has this label, such that any disk i= mages +created in this directory will automatically inherit the correct labelling= . If +attempting to use disk images in another location, the user/administrator = must +ensure the directory has be given this requisite label. Likewise physical = block +devices must be labelled ``system_u:object_r:virt_image_t``. + +Not all filesystems allow for labelling of individual files. In particular= NFS, +VFat and NTFS have no support for labelling. In these cases administrators= must +use the 'context' option when mounting the filesystem to set the default l= abel +to ``system_u:object_r:virt_image_t``. In the case of NFS, there is an +alternative option, of enabling the ``virt_use_nfs`` SELinux boolean. + +SELinux sVirt confinement +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SELinux sVirt protection for QEMU virtual machines builds to the basic= level +of protection, to also allow individual guests to be protected from each o= ther. + +In the sVirt model, each QEMU virtual machine runs under its own confined +domain, which is based on ``system_u:system_r:svirt_t:s0`` with a unique +category appended, eg, ``system_u:system_r:svirt_t:s0:c34,c44``. The rules= are +setup such that a domain can only access files which are labelled with the +matching category level, eg ``system_u:object_r:svirt_image_t:s0:c34,c44``= . This +prevents one QEMU process accessing any file resources that are prevent to +another QEMU process. + +There are two ways of assigning labels to virtual machines under sVirt. In= the +default setup, if sVirt is enabled, guests will get an automatically assig= ned +unique label each time they are booted. The libvirtd daemon will also +automatically relabel exclusive access disk images to match this label. Di= sks +that are marked as will get a generic label +``system_u:system_r:svirt_image_t:s0`` allowing all guests read/write acce= ss +them, while disks marked as will get a generic label +``system_u:system_r:svirt_content_t:s0`` which allows all guests read-only +access. + +With statically assigned labels, the application should include the desired +guest and file labels in the XML at time of creating the guest with libvir= t. In +this scenario the application is responsible for ensuring the disk images & +similar resources are suitably labelled to match, libvirtd will not attemp= t any +relabelling. + +If the sVirt security model is active, then the node capabilities XML will +include its details. If a virtual machine is currently protected by the se= curity +model, then the guest XML will include its assigned labels. If enabled at +compile time, the sVirt security model will always be activated if SELinux= is +available on the host OS. To disable sVirt, and revert to the basic level = of +SELinux protection (host protection only), the ``/etc/libvirt/qemu.conf`` = file +can be used to change the setting to ``security_driver=3D"none"`` + +AppArmor sVirt confinement +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using basic AppArmor protection for the libvirtd daemon and QEMU virt= ual +machines, the intention is to protect the host OS from a compromised virtu= al +machine process. There is no protection between guests. + +The AppArmor sVirt protection for QEMU virtual machines builds on this bas= ic +level of protection, to also allow individual guests to be protected from = each +other. + +In the sVirt model, if a profile is loaded for the libvirtd daemon, then e= ach +``qemu:///system`` QEMU virtual machine will have a profile created for it= when +the virtual machine is started if one does not already exist. This generat= ed +profile uses a profile name based on the UUID of the QEMU virtual machine = and +contains rules allowing access to only the files it needs to run, such as = its +disks, pid file and log files. Just before the QEMU virtual machine is sta= rted, +the libvirtd daemon will change into this unique profile, preventing the Q= EMU +process from accessing any file resources that are present in another QEMU +process or the host machine. + +The AppArmor sVirt implementation is flexible in that it allows an adminis= trator +to customize the template file in ``/etc/apparmor.d/libvirt/TEMPLATE`` for +site-specific access for all newly created QEMU virtual machines. Also, wh= en a +new profile is generated, two files are created: +``/etc/apparmor.d/libvirt/libvirt-`` and +``/etc/apparmor.d/libvirt/libvirt-.files``. The former can be fine-t= uned +by the administrator to allow custom access for this particular QEMU virtu= al +machine, and the latter will be updated appropriately when required file a= ccess +changes, such as when a disk is added. This flexibility allows for situati= ons +such as having one virtual machine in complain mode with all others in enf= orce +mode. + +While users can define their own AppArmor profile scheme, a typical +configuration will include a profile for ``/usr/sbin/libvirtd``, +``/usr/lib/libvirt/virt-aa-helper`` or ``/usr/libexec/virt-aa-helper``\ (a +helper program which the libvirtd daemon uses instead of manipulating AppA= rmor +directly), and an abstraction to be included by +``/etc/apparmor.d/libvirt/TEMPLATE`` (typically +``/etc/apparmor.d/abstractions/libvirt-qemu``). An example profile scheme = can be +found in the examples/apparmor directory of the source distribution. + +If the sVirt security model is active, then the node capabilities XML will +include its details. If a virtual machine is currently protected by the se= curity +model, then the guest XML will include its assigned profile name. If enabl= ed at +compile time, the sVirt security model will be activated if AppArmor is +available on the host OS and a profile for the libvirtd daemon is loaded w= hen +libvirtd is started. To disable sVirt, and revert to the basic level of Ap= pArmor +protection (host protection only), the ``/etc/libvirt/qemu.conf`` file can= be +used to change the setting to ``security_driver=3D"none"``. + +Cgroups device ACLs +~~~~~~~~~~~~~~~~~~~ + +Linux kernels have a capability known as "cgroups" which is used for resou= rce +management. It is implemented via a number of "controllers", each controll= er +covering a specific task/functional area. One of the available controllers= is +the "devices" controller, which is able to setup access control lists of +block/character devices that a cgroup should be allowed to access. If the +"devices" controller is mounted on a host, then libvirt will automatically +create a dedicated cgroup for each QEMU virtual machine and setup the devi= ce +access control list so that the QEMU process can only access shared device= s, and +explicitly assigned disks images backed by block devices. + +The list of shared devices a guest is allowed access to is + +:: + + /dev/null, /dev/full, /dev/zero, + /dev/random, /dev/urandom, + /dev/ptmx, /dev/kvm, + +In the event of unanticipated needs arising, this can be customized via the +``/etc/libvirt/qemu.conf`` file. To mount the cgroups device controller, t= he +following command should be run as root, prior to starting libvirtd + +:: + + mkdir /dev/cgroup + mount -t cgroup none /dev/cgroup -o devices + +libvirt will then place each virtual machine in a cgroup at +``/dev/cgroup/libvirt/qemu/$VMNAME/`` + +Import and export of libvirt domain XML configs +----------------------------------------------- + +The QEMU driver currently supports a single native config format known as +``qemu-argv``. The data for this format is expected to be a single line fi= rst a +list of environment variables, then the QEMu binary name, finally followed= by +the QEMU command line arguments + +Converting from QEMU args to domain XML +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Note:** this operation is :removed:`deleted as of 5.5.0` and will return= an +error. + +The ``virsh domxml-from-native`` provides a way to convert an existing set= of +QEMU args into a guest description using libvirt Domain XML that can then = be +used by libvirt. Please note that this command is intended to be used to c= onvert +existing qemu guests previously started from the command line to be managed +through libvirt. It should not be used a method of creating new guests from +scratch. New guests should be created using an application calling the lib= virt +APIs (see the `libvirt applications page `__ for some examples)= or by +manually crafting XML to pass to virsh. + +Converting from domain XML to QEMU args +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``virsh domxml-to-native`` provides a way to convert a guest descripti= on +using libvirt Domain XML, into a set of QEMU args that can be run manually= . Note +that currently the command line formatted by libvirt is no longer suited f= or +manually running qemu as the configuration expects various resources and o= pen +file descriptors passed to the process which are usually prepared by libvi= rtd. + +Pass-through of arbitrary qemu commands +--------------------------------------- + +Libvirt provides an XML namespace and an optional library ``libvirt-qemu.s= o`` +for dealing specifically with qemu. When used correctly, these extensions = allow +testing specific qemu features that have not yet been ported to the generic +libvirt XML and API interfaces. However, they are **unsupported**, in that= the +library is not guaranteed to have a stable API, abusing the library or XML= may +result in inconsistent state the crashes libvirtd, and upgrading either qe= mu-kvm +or libvirtd may break behavior of a domain that was relying on a qemu-spec= ific +pass-through. If you find yourself needing to use them to access a particu= lar +qemu feature, then please post an RFE to the libvirt mailing list to get t= hat +feature incorporated into the stable libvirt XML and API interfaces. + +The library provides two API: ``virDomainQemuMonitorCommand``, for sending= an +arbitrary monitor command (in either HMP or QMP format) to a qemu guest ( +:since:`Since 0.8.3` ), and ``virDomainQemuAttach``, for registering a qemu +domain that was manually started so that it can then be managed by libvirt= d ( +:since:`Since 0.9.4` , :removed:`removed as of 5.5.0` ). + +Additionally, the following XML additions allow fine-tuning of the command= line +given to qemu when starting a domain ( :since:`Since 0.8.3` ). In order to= use +the XML additions, it is necessary to issue an XML namespace request (the +special ``xmlns:name`` attribute) that pulls in +``http://libvirt.org/schemas/domain/qemu/1.0``; typically, the namespace is +given the name of ``qemu``. With the namespace in place, it is then possib= le to +add an element ```` under ``domain``, with the following +sub-elements repeated as often as needed: + +``qemu:arg`` + Add an additional command-line argument to the qemu process when starti= ng the + domain, given by the value of the attribute ``value``. +``qemu:env`` + Add an additional environment variable to the qemu process when startin= g the + domain, given with the name-value pair recorded in the attributes ``nam= e`` + and optional ``value``. + +Example: + +:: + + + QEMU-fedora-i686 + 219200 + + hvm + + + /usr/bin/qemu-system-x86_64 + + + + + + + +QEMU feature configuration for testing +-------------------------------------- + +In some cases e.g. when developing a new feature or for testing it may be +required to control a given qemu feature (or qemu capability) to test it b= efore +it's complete or disable it for debugging purposes. :since:`Since 5.5.0` i= t's +possible to use the same special qemu namespace as above +(``http://libvirt.org/schemas/domain/qemu/1.0``) and use ```` +element to add (````) or remove +(````) capability bits. The naming of the +feature bits is the same libvirt uses in the status XML. Note that this fe= ature +is meant for experiments only and should _not_ be used in production. + +Example: + +:: + + + testvm + + [...] + + + + + + + +Example domain XML config +------------------------- + +QEMU emulated guest on x86_64 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + QEMU-fedora-i686 + c7a5fdbd-cdaf-9455-926a-d65c16db1809 + 219200 + 219200 + 2 + + hvm + + + + /usr/bin/qemu-system-x86_64 + + + + + + + + + + + + + + + + +KVM hardware accelerated guest on i686 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + demo2 + 4dea24b3-1d52-d8f3-2516-782e98a23fa0 + 131072 + 1 + + hvm + + + + /usr/bin/qemu-kvm + + + + + + + + + + + diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 9392c80113..a7b1a6a0bd 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -8100,4 +8100,4 @@ Example configurations for each driver are provide on= the driver specific pages listed below - `Xen examples `__ -- `QEMU/KVM examples `__ +- `QEMU/KVM examples `__ diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.= rst index b06c311b1d..470de93168 100644 --- a/docs/manpages/virt-qemu-run.rst +++ b/docs/manpages/virt-qemu-run.rst @@ -36,7 +36,7 @@ OS any opportunity to gracefully shutdown. **NOTE: this tool is currently considered experimental.** Its usage and behaviour is still subject to change in future libvirt releases. For further information on its usage consult the -`QEMU driver documentation `= _. +`QEMU driver documentation `_. OPTIONS =3D=3D=3D=3D=3D=3D=3D diff --git a/docs/meson.build b/docs/meson.build index d2e685f673..2b2f7879ed 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -49,7 +49,6 @@ docs_html_in_files =3D [ 'drvlxc', 'drvnodedev', 'drvopenvz', - 'drvqemu', 'drvremote', 'drvsecret', 'drvtest', @@ -113,6 +112,7 @@ docs_rst_files =3D [ 'compiling', 'daemons', 'developer-tooling', + 'drvqemu', 'formatbackup', 'formatcheckpoint', 'formatdomain', --=20 2.29.2 From nobody Sat May 4 14:34:35 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1616178904; cv=none; d=zohomail.com; s=zohoarc; b=ePQi7et20Ldqx0PinIMfAWktiW2ZPj8Zqz87bu7CHgUEGZGXluQNVA5VnYNV+IWvnawrcnBt2huZt7Z4jK1FwBB8ofQGmPuY/grvbiIpyVVUaKehQ1z3ZS9NMEjdAmyImKtWp3h9pIMlx8bHBPuZXN7LJY73C0UPAKWCa/mCa4s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1616178904; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=dh9zFBWbtl+w58HFWPRxQIJTgxLMvqF6651vr2QWzzw=; b=KYil5yW8wxqkU3P4jdU4so1hFdJVNxuCuXZoDGHYC401gYOc59lNGeLi+6wU2I+/WL2IEiayNERHi4C+ZQ5SPgQdO7lmG6h5+zrC37bSH3vfMIokqiBROf5di1o1DTuhxX+EQCmJ3hEYeTOvC6mPWsg8MIAjst/+vrjxXgdA6S8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1616178904814439.804446325649; Fri, 19 Mar 2021 11:35:04 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-297-vTixRO_9NR2wxw2bmze7OQ-1; Fri, 19 Mar 2021 14:34:30 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 48E1F1084D6D; Fri, 19 Mar 2021 18:34:23 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 268AF5C27C; Fri, 19 Mar 2021 18:34:23 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id CDC8B1802135; Fri, 19 Mar 2021 18:34:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12JIY2dd024599 for ; Fri, 19 Mar 2021 14:34:02 -0400 Received: by smtp.corp.redhat.com (Postfix) id 9EF635D9F2; Fri, 19 Mar 2021 18:34:02 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.33]) by smtp.corp.redhat.com (Postfix) with ESMTP id DABD25D9E3 for ; Fri, 19 Mar 2021 18:34:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616178903; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=dh9zFBWbtl+w58HFWPRxQIJTgxLMvqF6651vr2QWzzw=; b=N3ACuJ5jhYiVSx1A+gA2z5Ye8QJ/FLitVLmM1TbW1VMny3WCUU8S0hvVxH8nl/AZETvDES 8jqVmCugFQPPMiUKCQUgSTNTWr+wmA2z3Rcg27V0Z0HqXForUNw8zgAhW4F1pYmy3cM8CE jNtESHQgHvRTLGKw+PLQYZS2Sb5wVAU= X-MC-Unique: vTixRO_9NR2wxw2bmze7OQ-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 2/6] qemu: capabilities: Introduce QEMU_CAPS_COMPAT_DEPRECATED Date: Fri, 19 Mar 2021 19:33:50 +0100 Message-Id: <521b1c665fa37c4c517342d922e11c34852b1a3d.1616173918.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" The capability is asserted if qemu supports the -compat deprecated-input=3D and deprecated-output=3D settings to control what should happen if deprecated fields are used in QMP. This will be used for a developer/tester-oriented setting which will aid us in catching use of deprecated settings sooner. Signed-off-by: Peter Krempa Reviewed-by: Martin Kletzander --- src/qemu/qemu_capabilities.c | 8 ++++++++ src/qemu/qemu_capabilities.h | 1 + tests/qemucapabilitiesdata/caps_6.0.0.x86_64.xml | 1 + 3 files changed, 10 insertions(+) diff --git a/src/qemu/qemu_capabilities.c b/src/qemu/qemu_capabilities.c index dc1b10cd66..beea57caf6 100644 --- a/src/qemu/qemu_capabilities.c +++ b/src/qemu/qemu_capabilities.c @@ -624,6 +624,7 @@ VIR_ENUM_IMPL(virQEMUCaps, "audiodev", "blockdev-backup", "object.qapified", + "compat-deprecated", ); @@ -5187,6 +5188,13 @@ virQEMUCapsInitProcessCapsInterlock(virQEMUCapsPtr q= emuCaps) if (virQEMUCapsGet(qemuCaps, QEMU_CAPS_BLOCKDEV)) virQEMUCapsSet(qemuCaps, QEMU_CAPS_BLOCKDEV_HOSTDEV_SCSI); + + /* The -compat qemu command line argument is implemented using a newer + * method which doesn't show up in query-command-line-options. As we'l= l use + * it only for development and testing purposes we can base the capabi= lity + * on a not entirely related witness. */ + if (virQEMUCapsGet(qemuCaps, QEMU_CAPS_OBJECT_QAPIFIED)) + virQEMUCapsSet(qemuCaps, QEMU_CAPS_COMPAT_DEPRECATED); } diff --git a/src/qemu/qemu_capabilities.h b/src/qemu/qemu_capabilities.h index da51a788fa..a66a48a351 100644 --- a/src/qemu/qemu_capabilities.h +++ b/src/qemu/qemu_capabilities.h @@ -604,6 +604,7 @@ typedef enum { /* virQEMUCapsFlags grouping marker for = syntax-check */ QEMU_CAPS_AUDIODEV, /* -audiodev instead of QEMU_AUDIO_DRV */ QEMU_CAPS_BLOCKDEV_BACKUP, /* qemu supports the blockdev-backup job */ QEMU_CAPS_OBJECT_QAPIFIED, /* parameters for object-add are formally d= escribed */ + QEMU_CAPS_COMPAT_DEPRECATED, /* -compat deprecated-(input|output) is s= upported */ QEMU_CAPS_LAST /* this must always be the last item */ } virQEMUCapsFlags; diff --git a/tests/qemucapabilitiesdata/caps_6.0.0.x86_64.xml b/tests/qemuc= apabilitiesdata/caps_6.0.0.x86_64.xml index 555b6b5317..458ae66719 100644 --- a/tests/qemucapabilitiesdata/caps_6.0.0.x86_64.xml +++ b/tests/qemucapabilitiesdata/caps_6.0.0.x86_64.xml @@ -260,6 +260,7 @@ + 5002050 0 43100242 --=20 2.29.2 From nobody Sat May 4 14:34:35 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1616178857; cv=none; d=zohomail.com; s=zohoarc; b=gMtcAZcLcsucO1L90I7cdJnQjkY8V+l7wD1wk2jxUexYAE+5+ChTrxXYXuFb1XRFovFeAScyPMFiMf0tt0ob17DGE8gBdpQrI4949t5I4HqtolSboFn3GLqmc3nYhofWzoCeIywvC3Od4zgtgy/1h8kvc2aBrRLoKqeP7dS2/+0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1616178857; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vyfwtjZyH3CepP4RpKkphXESxGqQZdwsEpUTd3DsQaQ=; b=mLJkfoXQzWqdqPm0SLZBxm+YGaY64OCwnYtjQDKELHpr84TZK1n2vVHbeXbazzT1EfXUebLH1cvTYgLlquJ8t+bK0VrpR8LeylmpjfswW6zzOOOqVy0zFwthx62ywPRK0PdPKGiF2gnPmqhrEwSjGbFOYzWvp/Ns2CvvGdCY1a0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1616178857470552.1531596811996; Fri, 19 Mar 2021 11:34:17 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-143-xOfIFkJ7Pwu-UqufoN7VxA-1; Fri, 19 Mar 2021 14:34:13 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id BB97C1084D68; Fri, 19 Mar 2021 18:34:06 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6E7DC60CEC; Fri, 19 Mar 2021 18:34:06 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 1FD401809C83; Fri, 19 Mar 2021 18:34:05 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12JIY3Fl024608 for ; Fri, 19 Mar 2021 14:34:03 -0400 Received: by smtp.corp.redhat.com (Postfix) id C8DB55DAA5; Fri, 19 Mar 2021 18:34:03 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.33]) by smtp.corp.redhat.com (Postfix) with ESMTP id 201EA5D9E3 for ; Fri, 19 Mar 2021 18:34:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616178856; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=vyfwtjZyH3CepP4RpKkphXESxGqQZdwsEpUTd3DsQaQ=; b=aO32NfARZddqjU8L1p+Y8w1P95loo0+5YVZPn67updgo8juxL3oyUhGFMFzfQIRcMdYBiR l95Cd0NMhdRxYMoIrCvZMNCPysbDS2lY9P5uLDKPVvyVwRAaAnXJjZQToMzto9Lh+iFqaW NU2oklNmBh0z72HyTiKIuQE9bT1Jpag= X-MC-Unique: xOfIFkJ7Pwu-UqufoN7VxA-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 3/6] qemu: conf: Add 'deprecation_behavior' setting to qemu.conf Date: Fri, 19 Mar 2021 19:33:51 +0100 Message-Id: <65906c042e4f55e4d3f01cb46bc82000306e4aa4.1616173918.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" New QEMU supports an harsh, but hard to ignore way to notify that the QMP user used an deprecated command. This is useful e.g. for developers to see that something needs to be fixed. This patch introduces a qemu.conf option to enable the setting in cases when qemu supports it so that developers and continiuous integration efforts are notified about use of deprecated fields while it's not late. The option is deliberately stored as string and not validated to prevent failures when downgrading qemu or libvirt versions. While we don't support this, the knob isn't meant for public consumption anyways. Signed-off-by: Peter Krempa Reviewed-by: Martin Kletzander --- src/qemu/libvirtd_qemu.aug | 1 + src/qemu/qemu.conf | 31 ++++++++++++++++++++++++++++++ src/qemu/qemu_conf.c | 4 ++++ src/qemu/qemu_conf.h | 2 ++ src/qemu/test_libvirtd_qemu.aug.in | 1 + 5 files changed, 39 insertions(+) diff --git a/src/qemu/libvirtd_qemu.aug b/src/qemu/libvirtd_qemu.aug index 3c1045858b..0f18775121 100644 --- a/src/qemu/libvirtd_qemu.aug +++ b/src/qemu/libvirtd_qemu.aug @@ -131,6 +131,7 @@ module Libvirtd_qemu =3D let debug_level_entry =3D int_entry "gluster_debug_level" | bool_entry "virtiofsd_debug" + | str_entry "deprecation_behavior" let memory_entry =3D str_entry "memory_backing_dir" diff --git a/src/qemu/qemu.conf b/src/qemu/qemu.conf index 0c1054f198..086d7d2296 100644 --- a/src/qemu/qemu.conf +++ b/src/qemu/qemu.conf @@ -922,3 +922,34 @@ # may change across versions. # #capability_filters =3D [ "capname" ] + +# 'deprecation_behavior' setting controls how the qemu process behaves tow= ards +# deprecated commands and arguments used by libvirt. +# +# This setting is meant for developers and CI efforts to make it obvious w= hen +# libvirt relies on fields which are deprecated so that it can be fixes as= soon +# as possible. +# +# Possible options are: +# "none" - (default) qemu is supposed to accept and output deprecated fi= elds +# and commands +# "omit" - qemu is instructed to omit deprecated fields on output, behav= iour +# towards fields and commadns from qemu is not changed +# "reject" - qemu is instructed to report an error if a deprecated command= or +# field is used by libvirtd +# "crash" - qemu crashes when an deprecated command or field is used by l= ibvirtd +# +# For both "reject" and "crash" qemu is instructed to omit any deprecated = fields +# on output. +# +# The "reject" option is less harsh towards the VMs but some code paths ig= nore +# errors reported by qemu and thus it may not be obvious that a deprecated +# command/field was used, thus it's suggested to use the "crash" option in= stead. +# +# In cases when qemu doesn't support configuring the behaviour this settin= g is +# silently ignored to allow testing older qemu versions without having to +# reconfigure libvirtd. +# +# DO NOT use in production. +# +#deprecation_behavior =3D "none" diff --git a/src/qemu/qemu_conf.c b/src/qemu/qemu_conf.c index 2bbc75024c..4f7c85cda1 100644 --- a/src/qemu/qemu_conf.c +++ b/src/qemu/qemu_conf.c @@ -380,6 +380,8 @@ static void virQEMUDriverConfigDispose(void *obj) g_free(cfg->swtpmStorageDir); g_strfreev(cfg->capabilityfilters); + + g_free(cfg->deprecationBehavior); } @@ -869,6 +871,8 @@ virQEMUDriverConfigLoadDebugEntry(virQEMUDriverConfigPt= r cfg, return -1; if (virConfGetValueBool(conf, "virtiofsd_debug", &cfg->virtiofsdDebug)= < 0) return -1; + if (virConfGetValueString(conf, "deprecation_behavior", &cfg->deprecat= ionBehavior) < 0) + return -1; return 0; } diff --git a/src/qemu/qemu_conf.h b/src/qemu/qemu_conf.h index 7025b5222e..e62cd88950 100644 --- a/src/qemu/qemu_conf.h +++ b/src/qemu/qemu_conf.h @@ -223,6 +223,8 @@ struct _virQEMUDriverConfig { gid_t swtpm_group; char **capabilityfilters; + + char *deprecationBehavior; }; G_DEFINE_AUTOPTR_CLEANUP_FUNC(virQEMUDriverConfig, virObjectUnref); diff --git a/src/qemu/test_libvirtd_qemu.aug.in b/src/qemu/test_libvirtd_qe= mu.aug.in index 9310dcec1c..20a89ade32 100644 --- a/src/qemu/test_libvirtd_qemu.aug.in +++ b/src/qemu/test_libvirtd_qemu.aug.in @@ -115,3 +115,4 @@ module Test_libvirtd_qemu =3D { "capability_filters" { "1" =3D "capname" } } +{ "deprecation_behavior" =3D "none" } --=20 2.29.2 From nobody Sat May 4 14:34:35 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1616178869; cv=none; d=zohomail.com; s=zohoarc; b=Wh4yCJFFfnJYn2VT+Ks2hQJSIH5pSxmzLfsVBOnXC0CcU35hiTYKWULT28BU0T8yIqIP1QQsWERHqIxcduB6t02aRI1ojE2Hkle8IcFpPxg4DlJWlGjUEcR6L1gBTkMYkqPZUfO/AApOUrCzO4j9+eE2G0QARxjZouYdo5fZS0k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1616178869; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=7kHslyQx6fNHj49O/DEvfnBI5KcP7YwcVmelGjBgH5U=; b=CuTaXfQqF9x1IMLGnch+Io20z4DgWGv2+ouVlAjjRSWgbYygW7IMjp76IhktnTP3cLock5KEyrd/UY6/hBEVwLi4ek5UN5R1w0gP29b2ZFnVhNN3PDnIT98zugIk2jgXCiBsbbdPqVIM/N1dVSFlFM/bjKnUz+B8dlLaXzruyn8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 16161788696495.664965494226067; Fri, 19 Mar 2021 11:34:29 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-323-Mamq5AOHMy-RFznIMl3U_g-1; Fri, 19 Mar 2021 14:34:24 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D23971009468; Fri, 19 Mar 2021 18:34:17 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id AB1FA5DAA5; Fri, 19 Mar 2021 18:34:17 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 64BF3180B451; Fri, 19 Mar 2021 18:34:17 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12JIY5g0024618 for ; Fri, 19 Mar 2021 14:34:05 -0400 Received: by smtp.corp.redhat.com (Postfix) id 0B65C5D9F2; Fri, 19 Mar 2021 18:34:05 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.33]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3E9D35D9E3 for ; Fri, 19 Mar 2021 18:34:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1616178867; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=7kHslyQx6fNHj49O/DEvfnBI5KcP7YwcVmelGjBgH5U=; b=i2W5EcvKK5FqqqtZ5QkLhTy1RT5c2jxP7YgeqwKrZRUtZ+yGdu6GPzn9cNuxPWmVU2KjR2 +B43FOAj/BNOAP0zakm9L1mt/Nnm8Gh+tTyOno1kOHlZ6fQpe1LqJMT7/RzHoA8+LyhvPp 9DS0YNGLu/Lt/1CsQbCJse6ZDw/s4CQ= X-MC-Unique: Mamq5AOHMy-RFznIMl3U_g-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 4/6] qemuxml2xmltest: Enable 'qemu-ns' case Date: Fri, 19 Mar 2021 19:33:52 +0100 Message-Id: <9929e729afcba146142ef1211ce8862b81e618e9.1616173918.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" The XML formatter validation was missing for this code path. Signed-off-by: Peter Krempa Reviewed-by: Martin Kletzander --- .../qemu-ns.x86_64-latest.xml | 51 +++++++++++++++++++ tests/qemuxml2xmltest.c | 1 + 2 files changed, 52 insertions(+) create mode 100644 tests/qemuxml2xmloutdata/qemu-ns.x86_64-latest.xml diff --git a/tests/qemuxml2xmloutdata/qemu-ns.x86_64-latest.xml b/tests/qem= uxml2xmloutdata/qemu-ns.x86_64-latest.xml new file mode 100644 index 0000000000..53e21edfaf --- /dev/null +++ b/tests/qemuxml2xmloutdata/qemu-ns.x86_64-latest.xml @@ -0,0 +1,51 @@ + + QEMUGuest1 + c7a5fdbd-edaf-9455-926a-d65c16db1809 + 219136 + 219136 + 1 + + hvm + + + + qemu64 + + + destroy + restart + destroy + + /usr/bin/qemu-system-i386 + + + + +
    + + +
    + + +
    + + + + +