- Devel - libvirt List Archives

[PATCH v2] docs: switch to GitLab issue tracker for security disclosures
by Daniel P. Berrangé 03 Aug '26

03 Aug '26

From: Daniel P. Berrangé <berrange(a)redhat.com> Use of email for security disclosures is not a sustainable approach in the new world with countless LLM assisted security researchers. The old security approach has been to keep disclosures visible to a very small number of hand-picked maintainers, on the assumption that information has to be highly classified. This view is no longer valid with LLMs assisted research, as multiple people can report the same flaw within a short window of time. It is assumed that anyone with access to LLMs will be capable of re-discovering issues at any time. As such there is less compelling benefit to limiting the visibility of disclosures originating with LLMs. Rather than try to distinguish which disclosures come purely from humans vs those assisted by LLMs, just assume LLMs will be involved as that is the common case. Thus make disclosures visible to all maintainers immediately. By the same rational of repeated re-discovery there is also less benefit to applying embargoes to issues once a fix is available. Thus this proposal intends to make CVEs public as soon as a fix is proposed for merge. With this new open approach to disclosures, there is then no reason to have a separate process for disclosing regular bugs vs security issues. By using the regular bug tracker for security disclosures, the process can be simplified and gain access to better tools for tracking & triage than email offers. Thus the new security disclosure process is simply with bug tracking process with two add-ons: * The initial disclosure has the "confidential" flag set * The use of "CVE::Required" and "CVE::Assigned" labels to handle CVE allocation. This is essentially identical to the process adopted by QEMU last month which has been successful at scaling the triage process. Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com> --- docs/securityprocess.rst | 96 +++++++++++++++++++--------------------- 1 file changed, 45 insertions(+), 51 deletions(-) diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index b7695ddc59..61261c82b0 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -4,30 +4,30 @@ Security Process .. contents:: -The libvirt project believes in responsible disclosure of security problems, to -allow vendors time to prepare and distribute patches for problems ahead of their -publication. This page describes how the process works and how to report -potential security issues. +The libvirt project handles security disclosures with a lightweight process +whose aim is to minimize the overhead of triage and prioritize publication +of a patch that addresses the issue. Reporting security issues ------------------------- -In the event that a bug in libvirt is found which is believed to have -(potential) security implications there is a dedicated contact to which a bug -report / notification should be directed. Send an email with as many details of -the problem as possible (ideally with steps to reproduce) to the following email -address: +Security concerns should be reported as confidential issues in the +`libvirt project on GitLab <https://gitlab.com/libvirt/libvirt/-/work_items>`__, or one of the other related projects under the +`libvirt namespace <https://gitlab.com/libvirt/>`__ if the issue does not +apply to the core project. -:: +Ensure that the "**turn on confidentiality**" checkbox is selected prior to +submitting the issue, to restrict visibility to project maintainers only. - security(a)lists.libvirt.org +Maintainer(s) will analyse the reported disclosure and decide whether it +is to be classed as a security flaw or not. If not a security flaw, the +``confidential`` tag will be removed immediately. If a security flaw, +the maintainers will work to develop and test a patch. When a suitable +patch is considered ready to post to the mailing list or a merge request, +the ``confidential`` tag will be removed. Generally a CVE should be assignd +to a security issue before a patch is ready to be posted (see below). -NB. while this email address is backed by a mailing list, it is invitation only -and moderated for non-members. As such you will receive an auto-reply indicating -the report is held for moderation. Postings by non-members will be approved by a -moderator and the reporter copied on any replies. - -Refer to the `bug reporting <bugs.html#use-of-automated-tools-ai-agents>`__ +Note: Refer to the `bug reporting <bugs.html#use-of-automated-tools-ai-agents>`__ page for the *expectations around the use of automated tools and AI agents*, **prior** to filing any security report. @@ -42,48 +42,42 @@ formats. Security notices are published on the `libvirt-announce mailing list <contact.html#mailing-lists>`__ when any embargo is lifted, or as soon as triaged if already public knowledge. -Security team -------------- +Publication embargo policy +-------------------------- -The libvirt security team is made up of a subset of the libvirt core development -team which covers the various distro maintainers of libvirt, along with -nominated security engineers representing the various vendors who distribute -libvirt. The team is responsible for analysing incoming reports from users to -identify whether a security problem exists and its severity. It then works to -produce a fix for all official stable branches of libvirt and coordinate embargo -dates between vendors to allow simultaneous release of the fix by all affected -parties. +The libvirt project policy is to limit the time that a disclosure has the +"*confidential*" marker applied strictly to the minimum required to develop +and publish a suitable patch and allocate a CVE. -If you are a security representative of a vendor distributing libvirt and would -like to join the security team, send an email to the afore-mentioned security -address. Typically an existing member of the security team will have to vouch -for your credentials before membership is approved. All members of the security -team are **required to respect the embargo policy** described below. +Given the widespread use of AI/LLM based agents for security auditing, +as well as ongoing use of traditional fuzzing and static analysis +tools, the libvirt maintainers consider that any disclosure originating +from automated tools is highly likely to be independently re-discovered, +potentially many times over in a very short timeframe. -Publication embargo policy --------------------------- +Thus the libvirt maintainers will generally reject requests for arbitrary +embargoes unless high severity, extenuating circumstances can be +demonstrated. -The libvirt security team operates a policy of `responsible -disclosure <https://en.wikipedia.org/wiki/Responsible_disclosure>`__. As such -any security issue reported, that is not already publicly disclosed elsewhere, -will have an embargo date assigned. Members of the security team agree not to -publicly disclose any details of the security issue until the embargo date -expires. - -The general aim of the team is to have embargo dates which are two weeks or less -in duration. If a problem is identified with a proposed patch for a security -issue, requiring further investigation and bug fixing, the embargo clock may be -restarted. In exceptional circumstances longer initial embargoes may be -negotiated by mutual agreement between members of the security team and other -relevant parties to the problem. Any such extended embargoes will aim to be at -most one month in duration. +If a patch for a confirmed security issue cannot be developed by a +maintainer in a reasonable time, the maintainers may choose to make +a disclosure public without having a patch available. This approach +should only be taken for issues judged to have low severity. CVE allocation -------------- -The libvirt security team will associate each security issue with a CVE number. -The CVE numbers will usually be allocated by one of the vendor security -engineers on the security team. +If a reported disclosure is confirmed to be a security flaw, the +``CVE::Required`` label will be added. + +When a CVE has been allocated, this label will be removd and replaced +by ``CVE::Assigned``. + +The allocated CVE identifier will be included in the patch(es) that +are required to fix the issue. If multiple patches are involved, the +CVE must be included in the final patch in the series that closes the +last hole, but should also be included in any prior patches it the +series that are directly related. Branch fixing policy -------------------- -- 2.55.0

2 1

[PATCH] docs: switch to GitLab issue tracker for security disclosures
by Daniel P. Berrangé 03 Aug '26

03 Aug '26

From: Daniel P. Berrangé <berrange(a)redhat.com> Use of email for security disclosures is not a sustainable approach in the new world with countless LLM assisted security researchers. The old security approach has been to keep disclosures visible to a very small number of hand-picked maintainers, on the assumption that information has to be highly classified. This view is no longer valid with LLMs assisted research, as multiple people can report the same flaw within a short window of time. It is assumed that anyone with access to LLMs will be capable of re-discovering issues at any time. As such there is less compelling benefit to limiting the visibility of disclosures originating with LLMs. Rather than try to distinguish which disclosures come purely from humans vs those assisted by LLMs, just assume LLMs will be involved as that is the common case. Thus make disclosures visible to all maintainers immediately. By the same rational of repeated re-discovery there is also less benefit to applying embargoes to issues once a fix is available. Thus this proposal intends to make CVEs public as soon as a fix is proposed for merge. With this new open approach to disclosures, there is then no reason to have a separate process for disclosing regular bugs vs security issues. By using the regular bug tracker for security disclosures, the process can be simplified and gain access to better tools for tracking & triage than email offers. Thus the new security disclosure process is simply with bug tracking process with two add-ons: * The initial disclosure has the "confidential" flag set * The use of "CVE::Required" and "CVE::Assigned" labels to handle CVE allocation. This is essentially identical to the process adopted by QEMU last month which has been successful at scaling the triage process. Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com> --- docs/securityprocess.rst | 94 ++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 51 deletions(-) diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index b7695ddc59..0cc1349b9e 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -4,30 +4,28 @@ Security Process .. contents:: -The libvirt project believes in responsible disclosure of security problems, to -allow vendors time to prepare and distribute patches for problems ahead of their -publication. This page describes how the process works and how to report -potential security issues. +The libvirt project handles security disclosures with a lightweight process +whose aim is to minimize the overhead of triage and prioritize publication +of a patch that addresses the issue. Reporting security issues ------------------------- -In the event that a bug in libvirt is found which is believed to have -(potential) security implications there is a dedicated contact to which a bug -report / notification should be directed. Send an email with as many details of -the problem as possible (ideally with steps to reproduce) to the following email -address: +Security concerns in libvirt should be reported as confidential issues in +the appropriate `project on GitLab. <https://gitlab.com/libvirt>`__. -:: +Ensure that the "**turn on confidentiality**" checkbox is selected prior to +submitting the issue, to restrict visibility to project maintainers only. - security(a)lists.libvirt.org +Maintainer(s) will analyse the reported disclosure and decide whether it +is to be classed as a security flaw or not. If not a security flaw, the +``confidential`` tag will be removed immediately. If a security flaw, +the maintainers will work to develop and test a patch. When a suitable +patch is considered ready to post to the mailing list or a merge request, +the ``confidential`` tag will be removed. Generally a CVE should be assignd +to a security issue before a patch is ready to be posted (see below). -NB. while this email address is backed by a mailing list, it is invitation only -and moderated for non-members. As such you will receive an auto-reply indicating -the report is held for moderation. Postings by non-members will be approved by a -moderator and the reporter copied on any replies. - -Refer to the `bug reporting <bugs.html#use-of-automated-tools-ai-agents>`__ +Note: Refer to the `bug reporting <bugs.html#use-of-automated-tools-ai-agents>`__ page for the *expectations around the use of automated tools and AI agents*, **prior** to filing any security report. @@ -42,48 +40,42 @@ formats. Security notices are published on the `libvirt-announce mailing list <contact.html#mailing-lists>`__ when any embargo is lifted, or as soon as triaged if already public knowledge. -Security team -------------- +Publication embargo policy +-------------------------- -The libvirt security team is made up of a subset of the libvirt core development -team which covers the various distro maintainers of libvirt, along with -nominated security engineers representing the various vendors who distribute -libvirt. The team is responsible for analysing incoming reports from users to -identify whether a security problem exists and its severity. It then works to -produce a fix for all official stable branches of libvirt and coordinate embargo -dates between vendors to allow simultaneous release of the fix by all affected -parties. +The libvirt project policy is to limit the time that a disclosure has the +"*confidential*" marker applied strictly to the minimum required to develop +and publish a suitable patch and allocate a CVE. -If you are a security representative of a vendor distributing libvirt and would -like to join the security team, send an email to the afore-mentioned security -address. Typically an existing member of the security team will have to vouch -for your credentials before membership is approved. All members of the security -team are **required to respect the embargo policy** described below. +Given the widespread use of AI/LLM based agents for security auditing, +as well as ongoing use of traditional fuzzing and static analysis +tools, the QEMU maintainers consider that any disclosure originating +from automated tools is highly likely to be independently re-discovered, +potentially many times over in a very short timeframe. -Publication embargo policy --------------------------- +Thus the QEMU maintainers will generally reject requests for arbitrary +embargoes unless high severity, extenuating circumstances can be +demonstrated. -The libvirt security team operates a policy of `responsible -disclosure <https://en.wikipedia.org/wiki/Responsible_disclosure>`__. As such -any security issue reported, that is not already publicly disclosed elsewhere, -will have an embargo date assigned. Members of the security team agree not to -publicly disclose any details of the security issue until the embargo date -expires. - -The general aim of the team is to have embargo dates which are two weeks or less -in duration. If a problem is identified with a proposed patch for a security -issue, requiring further investigation and bug fixing, the embargo clock may be -restarted. In exceptional circumstances longer initial embargoes may be -negotiated by mutual agreement between members of the security team and other -relevant parties to the problem. Any such extended embargoes will aim to be at -most one month in duration. +If a patch for a confirmed security issue cannot be developed by a +maintainer in a reasonable time, the maintainers may choose to make +a disclosure public without having a patch available. This approach +should only be taken for issues judged to have low severity. CVE allocation -------------- -The libvirt security team will associate each security issue with a CVE number. -The CVE numbers will usually be allocated by one of the vendor security -engineers on the security team. +If a reported disclosure is confirmed to be a security flaw, the +``CVE::Required`` label will be added. + +When a CVE has been allocated, this label will be removd and replaced +by ``CVE::Assigned``. + +The allocated CVE identifier will be included in the patch(es) that +are required to fix the issue. If multiple patches are involved, the +CVE must be included in the final patch in the series that closes the +last hole, but should also be included in any prior patches it the +series that are directly related. Branch fixing policy -------------------- -- 2.55.0

2 2

Release of libvirt-12.6.0
by Jiri Denemark 03 Aug '26

03 Aug '26

The 12.6.0 release of both libvirt and libvirt-python is tagged and signed tarballs are available at https://download.libvirt.org/ https://download.libvirt.org/python/ Thanks everybody who helped with this release by sending patches, reviewing, testing, or providing feedback. Your work is greatly appreciated. * New features * bhyve: implement ``virDomainRename()`` The bhyve driver now implements the ``virDomainRename()`` API for renaming of a domain (``virsh domrename``). * build: Add option to control building libvirtd Meson option ``libvirtd`` has been added to control building the monolithic libvirtd, independent from the stateful, daemon-based drivers. * sanlock: Add option to check ownership of disk leases The sanlock lock driver plugin now supports the ``check_disk_lease_owner`` setting in sanlock.conf. When enabled, the sanlock plugin will check that leases are owned by the domain attempting to acquire them. * Improvements * qemu: Add ``preserve-running`` action for ``<on_crash>`` Allow qemu VMs to be kept running after they notify that they've crashed. This is useful for guests that can take their own crash dump and reboot. Enjoy. Jirka

1 0

[PATCH] bhyve: capabilities: use full path for emulator
by Roman Bogorodskiy 03 Aug '26

03 Aug '26

Currently, when the bhyve driver builds capabilities, it uses just "bhyve" as emulator path. That leads to issues, e.g. virt-manager uses this value to fill domain's emulator field, which has to be an absolute path. So that results in a domain XML that fails validation. Fix by trying to find "bhyve" in PATH and falling back to "/usr/sbin/bhyve". Closes: https://gitlab.com/libvirt/libvirt/-/work_items/899 Signed-off-by: Roman Bogorodskiy <bogorodskiy(a)gmail.com> --- src/bhyve/bhyve_capabilities.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/bhyve/bhyve_capabilities.c b/src/bhyve/bhyve_capabilities.c index 1fe0a3ad77..85988a2ce8 100644 --- a/src/bhyve/bhyve_capabilities.c +++ b/src/bhyve/bhyve_capabilities.c @@ -48,13 +48,14 @@ virBhyveCapsBuild(void) virCaps *caps; virCapsGuest *guest; virArch hostarch = virArchFromHost(); + g_autofree char *binary = virFindFileInPath("bhyve"); if ((caps = virCapabilitiesNew(hostarch, false, false)) == NULL) return NULL; guest = virCapabilitiesAddGuest(caps, VIR_DOMAIN_OSTYPE_HVM, - hostarch, "bhyve", + hostarch, binary ? binary : "/usr/sbin/bhyve", NULL, 0, NULL); virCapabilitiesAddGuestDomain(guest, VIR_DOMAIN_VIRT_BHYVE, -- 2.52.0

3 3

[PATCH] NEWS: Mention the 'preserve-running' action for '<on_crash>'
by Peter Krempa 03 Aug '26

03 Aug '26

From: Peter Krempa <pkrempa(a)redhat.com> Signed-off-by: Peter Krempa <pkrempa(a)redhat.com> --- NEWS.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/NEWS.rst b/NEWS.rst index 50b086b789..a4bd015c15 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -35,6 +35,11 @@ v12.6.0 (unreleased) * **Improvements** + * qemu: Add ``preserve-running`` action for ``<on_crash>`` + + Allow qemu VMs to be kept running after they notify that they've crashed. + This is useful for guests that can take their own crash dump and reboot. + * **Bug fixes** -- 2.55.0

2 1

Entering freeze for libvirt-12.6.0
by Jiri Denemark 30 Jul '26

30 Jul '26

I have just tagged v12.6.0-rc1 in the repository and pushed signed tarballs to https://download.libvirt.org/ Please give the release candidate some testing and in case you find a serious issue which should have a fix in the upcoming release, feel free to reply to this thread to make sure the issue is more visible. If you have not done so yet, please update NEWS.rst to document any significant change you made since the last release. Jirka

1 1

[PATCH 0/4] qemu: auto-select win-dmp for Windows guest crash dumps
by Denis V. Lunev 30 Jul '26

30 Jul '26

Auto-triggered dumps (on_crash, watchdog) always use QEMU's elf default, which is not WinDbg-loadable for a Windows guest and cannot be reliably converted after the fact. This was proposed before as a per-domain XML knob (https://www.mail-archive.com/devel@lists.libvirt.org/msg09638.html) Daniel P. Berrange objected: QEMU's query-dump-guest-memory-capability reported win-dmp as available on any x86-64 guest regardless of whether it had actually published a Windows dump header, so trusting it was not safe. QEMU's win_dump_available() has since been fixed to check the guest's vmcoreinfo note (https://lore.kernel.org/qemu-devel/20260619101834.228432-1-den@openvz.org/, commit b4bdad7dce). Patch 1 queries it directly instead of adding an XML knob. Patch 4 adds a quota (auto_dump_max_size): a guest that keeps crashing otherwise fills auto_dump_path one dump at a time. Oldest dumps are pruned after each new one; the dump just written is never removed, even alone over quota. Patches 2-3 give that setting and virtlogd's max_size a "10GiB"-style syntax instead of a raw byte count, reusing virScaleInteger()'s existing unit table. Validated against real guests: a Windows Server 2022 guest crashed via Sysinternals NotMyFault produces a PAGEDU64 (win-dmp) dump; an AlmaLinux 9 guest crashed via sysrq produces an ELF one. A 1GiB quota across two Linux crashes pruned the older dump and kept the newer, over-quota one. syntax-check and virstringtest pass. Denis V. Lunev (4): qemu: auto-select win-dmp for crash- and watchdog-triggered dumps util: add virStrToBytes() and virConfGetValueBytes() for scaled sizes logging: accept a unit suffix in virtlogd's max_size qemu: cap total size of auto-triggered dumps under auto_dump_path src/libvirt_private.syms | 2 + src/logging/log_daemon_config.c | 2 +- src/logging/log_daemon_config.h | 2 +- src/logging/virtlogd.conf | 7 +- src/qemu/qemu.conf.in | 16 ++++ src/qemu/qemu_conf.c | 2 + src/qemu/qemu_conf.h | 1 + src/qemu/qemu_driver.c | 127 +++++++++++++++++++++++++++++++- src/util/virconf.c | 47 ++++++++++++ src/util/virconf.h | 3 + src/util/virutil.c | 23 ++++++ src/util/virutil.h | 5 ++ tests/virstringtest.c | 76 +++++++++++++++++++ 13 files changed, 308 insertions(+), 5 deletions(-) -- 2.53.0

3 15

[PATCH] util: virFileChownFiles: do not follow symlinks
by Daniel P. Berrangé 30 Jul '26

30 Jul '26

From: HE WEI（ギカク） <skyexpoc(a)gmail.com> virFileChownFiles() selected entries with virFileIsRegular() (stat(), follows symlinks) and changed ownership with chown() (follows symlinks). A component that owns the target directory at a lower privilege (e.g. the swtpm/tss state directory) can plant a symlink to an arbitrary regular file and have the root caller chown that file. Use lstat() to skip non-regular entries and fchownat(..., AT_SYMLINK_NOFOLLOW) so a symlink final component is never followed. Fixes: CVE-2026-63622 Signed-off-by: HE WEI（ギカク） <skyexpoc(a)gmail.com> [DB: use g_lstat instead of stat; use lchown instead of fchownat for portability; added comment] Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com> --- src/util/virfile.c | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/util/virfile.c b/src/util/virfile.c index a0c6cb8048..c9d838eeeb 100644 --- a/src/util/virfile.c +++ b/src/util/virfile.c @@ -3306,6 +3306,12 @@ int virDirIsEmpty(const char *path, * * Change ownership of all regular files in a directory. * + * This will NOT follow any symlinks, to avoid security risks. + * It is assumed the process using content under @name will + * be unprivileged, thus less trusted than libvirt. If it is + * compromised it might attempt to create symlinks in @name to + * escalate privileges on a subsequent call to virFileChownFiles. + * * Returns -1 on error, with error already reported, 0 on success. */ #ifndef WIN32 @@ -3322,13 +3328,19 @@ int virFileChownFiles(const char *name, while ((direrr = virDirRead(dir, &ent, name)) > 0) { g_autofree char *path = NULL; + struct stat sb; path = g_build_filename(name, ent->d_name, NULL); - if (!virFileIsRegular(path)) + if (g_lstat(path, &sb) < 0) { + virReportSystemError(errno, _("cannot stat '%1$s'"), path); + return -1; + } + + if (!S_ISREG(sb.st_mode)) continue; - if (chown(path, uid, gid) < 0) { + if (lchown(path, uid, gid) < 0) { virReportSystemError(errno, _("cannot chown '%1$s' to (%2$u, %3$u)"), ent->d_name, (unsigned int) uid, -- 2.55.0

2 1

[PATCH] storage: create images with a private umask during qemu-img create/convert
by Daniel P. Berrangé 30 Jul '26

30 Jul '26

From: HE WEI（ギカク） <skyexpoc(a)gmail.com> On the local (non-NETFS) path virStorageBackendCreateExecCommand() ran qemu-img with umask 0, so the destination image was created world-readable (0644) and the full source disk was written into it before libvirt tightened the mode with a later chmod(). This is the same class as CVE-2025-13193; apply the same fix by setting a 0077 umask so qemu-img creates the file private from the start. Fixes: CVE-2026-63623 Reported-by: HE WEI（ギカク） <skyexpoc(a)gmail.com> Signed-off-by: HE WEI（ギカク） <skyexpoc(a)gmail.com> [DB: merged the two virCommandSetUmask to one] Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com> --- src/storage/storage_util.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/storage/storage_util.c b/src/storage/storage_util.c index 78dc9f9f1c..9e6b266842 100644 --- a/src/storage/storage_util.c +++ b/src/storage/storage_util.c @@ -464,6 +464,7 @@ virStorageBackendCreateExecCommand(virStoragePoolObj *pool, bool filecreated = false; int ret = -1; + virCommandSetUmask(cmd, S_IRWXUGO ^ mode); if ((def->type == VIR_STORAGE_POOL_NETFS) && (((geteuid() == 0) && (vol->target.perms->uid != (uid_t)-1) @@ -473,7 +474,6 @@ virStorageBackendCreateExecCommand(virStoragePoolObj *pool, virCommandSetUID(cmd, vol->target.perms->uid); virCommandSetGID(cmd, vol->target.perms->gid); - virCommandSetUmask(cmd, S_IRWXUGO ^ mode); if (virCommandRun(cmd, NULL) == 0) { /* command was successfully run, check if the file was created */ @@ -505,7 +505,6 @@ virStorageBackendCreateExecCommand(virStoragePoolObj *pool, /* don't change uid/gid/mode if we retry */ virCommandSetUID(cmd, -1); virCommandSetGID(cmd, -1); - virCommandSetUmask(cmd, 0); if (virCommandRun(cmd, NULL) < 0) goto cleanup; -- 2.55.0

2 1

[libvirt-python] RFC: Adding Sphinx API documentation for Python bindings
by Radoslaw Smigielski 30 Jul '26

30 Jul '26

Hi, I'd like to propose adding generated API documentation for the libvirt-python bindings and would appreciate the community's opinion on whether this is worthwhile. The problem: The libvirt-python bindings currently have no browsable API documentation. Users who want to discover available methods, their parameters, or behavior have to either read the C API docs and map them to Python or inspect the generated libvirt.py source directly, or rely on IDE auto-completion. But in the same time the infrastructure to produce good documentation is already in place, I mean XML API descriptions libvirt-api.xml, generator.py and override files (libvirt-override-virDomain.py, etc.) also contain docstrings. These docstrings are present but are not rendered anywhere for users to browse. The proposal: Add a minimal Sphinx setup (docs/conf.py, a few .rst files, and a requirements-docs.txt) to generate HTML API reference from the existing docstrings. This would cover all four modules: libvirt, libvirt_qemu, libvirt_lxc, and libvirtaio. This is a working prototype that builds successfully and produces complete API reference pages. https://gitlab.com/rsmigiel/libvirt-python/-/commit/53b1fdeca932de7b8deffb2… Would this be a welcome change? Any concerns or suggestions on the approach? Thanks for your feedback! ---------------------- < Tℏanks | Radek >

2 2