add "dump memory file from guest" feature

nickzhq · nickzhq · commit 07747a96ba40 · 2026-02-05T13:49:30.000+08:00
- Add guest_dump_file_manager.py
- Add dump_file.py
- Update env_process.py

Add "dump memory file" step in postprocess_vm function
The guest_dump_file_manager.py implements the main function
The dump_file.py implements "prepare the environment"

Signed-off-by: Houqi (Nick) Zuo &lt;hzuo@redhat.com&gt;
diff --git a/virttest/env_process.py b/virttest/env_process.py
@@ -24,6 +24,7 @@
     cpu,
     data_dir,
     error_context,
+    guest_dump_file_manager,
     libvirt_version,
     png_utils,
     ppm_utils,
@@ -45,6 +46,7 @@
 from virttest._wrappers import lazy_import
 from virttest.test_setup.aexpect import KillTailThreads
 from virttest.test_setup.core import SetupManager
+from virttest.test_setup.dump_file import DumpFileSetup
 from virttest.test_setup.gcov import ResetQemuGCov
 from virttest.test_setup.kernel import KSMSetup, ReloadKVMModules
 from virttest.test_setup.libvirt_setup import LibvirtdDebugLogConfig
@@ -641,6 +643,9 @@ def postprocess_vm(test, params, env, name):
     if not vm:
         return
 
+    _mgr = guest_dump_file_manager.get_dump_file_mgr(params.get("vm_type"))
+    if params.get("dumping_guest_memory", "") == "online" and _mgr:
+        _mgr.run(params, test.outputdir)
     if params.get("start_vm") == "yes":
         # recover the changes done to kernel params in postprocess
         serial_login = params.get_boolean("kernel_extra_params_serial_login")
@@ -707,6 +712,12 @@ def postprocess_vm(test, params, env, name):
             if vm.devices is not None:
                 vm.devices.cleanup_daemons()
 
+            if params.get("dumping_guest_memory", "") == "offline" and _mgr:
+                base_dir = params.get("images_base_dir", data_dir.get_data_dir())
+                _img = params.objects("images")[0]
+                _sys_image = qemu_storage.QemuImg(params, base_dir, _img)
+                _mgr.run(params, test.outputdir, _sys_image.image_filename)
+
     if params.get("enable_strace") == "yes":
         strace = test_setup.StraceQemu(test, params, env)
         strace.stop()
@@ -1029,6 +1040,8 @@ def preprocess(test, params, env):
     _setup_manager.register(TransparentHugePagesSetup)
     _setup_manager.register(KSMSetup)
     _setup_manager.register(EGDSetup)
+    if params.get("dumping_guest_memory", "") == "offline":
+        _setup_manager.register(DumpFileSetup)
     _setup_manager.do_setup()
 
     vm_type = params.get("vm_type")
diff --git a/virttest/guest_dump_file_manager.py b/virttest/guest_dump_file_manager.py
@@ -0,0 +1,328 @@
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See LICENSE for more details.
+#
+# Copyright: Red Hat Inc. 2026
+# Authors: Houqi (Nick) Zuo <hzuo@redhat.com>
+
+import logging
+import os
+import shutil
+
+from avocado.utils import linux_modules, process
+
+from virttest import utils_misc
+
+LOG = logging.getLogger(__name__)
+
+
+class GuestDumpFileManager(object):
+    """
+    Base class for managing dump files from guest.
+
+    This class provides the basic structure and common functionality
+    for extracting dump files from guest disk images.
+    """
+
+    def __init__(self):
+        """
+        Initialize the GuestDumpFileManager.
+
+        Sets up the mount point, NBD device variables, guest type,
+        partition information, filesystem support mapping, and
+        directories to scan for dump files.
+        """
+        self._mount_pt = "/mnt/guest"
+        self._nbd_dev = ""  # nbd15
+        self._nbd_dev_partition_path = ""  # /dev/nbd15p3
+        self._guest_type = ""  # linux or windows
+        self._partition_list = []
+        self._partition_fstype = ""
+        self._fs_support_mapping = {
+            "ntfs": self._ntfs,
+            "LVM2_member": self._lvm2_member,
+        }
+        self._dmp_dirs_scaned = {
+            "windows": [
+                "%s/Windows" % self._mount_pt,
+                "%s/Windows/Minidump" % self._mount_pt,
+                "%s/Windows/Temp" % self._mount_pt,
+                "%s/Windows/LiveKernelReports" % self._mount_pt,
+                "%s/Windows/ProgramData/Microsoft/Windows/WER" % self._mount_pt,
+            ],
+            "linux": [],
+        }
+        self._os_type_mapping = {
+            "windows": "Microsoft basic data",
+            "linux": "Linux LVM",
+        }
+
+    def run(self, params, res_dir, image_path=None):
+        """
+        Execute the dump file collection process.
+
+        This method should be implemented by subclasses to perform
+        the complete workflow of mounting the image and extracting dump files.
+
+        :param image_path: Path to the guest disk image.
+        :type image_path: str
+        :param res_dir: The path where results should be stored.
+        :type res_dir: str
+        :param params: Parameters of vm.
+        :type params: dict
+        """
+        _run = {
+            "online": self._run_online,
+            "offline": self._run_offline,
+        }
+        _run[params.get("dumping_guest_memory")](params, res_dir, image_path)
+
+    def _run_online(self, params, res_dir, image_path=None):
+        """
+        Execute the dump file collection process via qmp.
+
+        This method should be implemented by subclasses to perform
+        the complete workflow of mounting the image and extracting dump files.
+
+        :param image_path: Path to the guest disk image.
+        :type image_path: str
+        :param res_dir: The path where results should be stored.
+        :type res_dir: str
+        :param params: Parameters of vm.
+        :type params: dict
+        """
+        raise NotImplementedError("Online dump-file collection is not implemented")
+
+    def _run_offline(self, params, res_dir, image_path):
+        """
+        Execute the dump file collection process via mounting the image.
+
+        This method should be implemented by subclasses to perform
+        the complete workflow of mounting the image and extracting dump files.
+
+        :param image_path: Path to the guest disk image.
+        :type image_path: str
+        :param res_dir: The path where results should be stored.
+        :type res_dir: str
+        :param params: Parameters of vm.
+        :type params: dict
+        """
+        raise NotImplementedError("Offline dump-file collection is not implemented")
+
+    def _ntfs(self):
+        """
+        Get the filesystem type for NTFS partitions.
+
+        :return: String representing the NTFS filesystem type ("ntfs-3g").
+        """
+        # NOTE:
+        # ntfs-3g permission means rw
+        # ntfs permission means read-only
+        return "ntfs"
+
+    def _lvm2_member(self):
+        """
+        Get the filesystem type for LVM2 partitions.
+
+        Note: LVM2_member cannot be mounted directly and requires
+        additional steps to access the logical volumes.
+
+        :return: Empty string (not yet implemented).
+        """
+        # The lvm2_member type (guest type is Linux) is generated by vt default
+        # TODO: Support the linux guest. lvm2_member can NOT be used  directly. And some steps are needed.
+        return None
+
+
+class QemuDumpFileManager(GuestDumpFileManager):
+    """
+    Dump file manager for QEMU/KVM virtual machine.
+
+    This class implements the dump file extraction process for
+    QEMU disk images using NBD (Network Block Device).
+    """
+
+    def __init__(self):
+        """
+        Initialize the QemuDumpFileManager.
+
+        Sets up the command for finding available NBD devices.
+        """
+        super(QemuDumpFileManager, self).__init__()
+        self._nbd_dev_cmd = "lsblk --output NAME,SIZE,MOUNTPOINT --noheadings"
+
+    def _process_dump_file_from_guest(self, res_dir):
+        """
+        Process dump files from the mounted guest disk filesystem.
+
+        Searches for dump files in predefined directories and moves
+        them to the results directory.
+
+        :param res_dir: Directory where results should be stored.
+        :type res_dir: str
+        """
+        _dirs = []
+        for item in self._dmp_dirs_scaned[self._guest_type]:
+            if os.path.exists(os.path.join(self._mount_pt, item)):
+                _dirs.append(item)
+        _dirs = " ".join(_dirs)
+        _cmd = 'find %s -maxdepth 1 -type f -iname "*.dmp"' % _dirs
+        _find_dmp_in_path = process.run(_cmd).stdout_text
+        if _find_dmp_in_path:
+            _find_dmp_in_path = _find_dmp_in_path.strip().splitlines()
+            res_dir = os.path.join(res_dir, "dump_file_from_guest")
+            if not os.path.exists(res_dir):
+                os.makedirs(res_dir)
+            for _path in _find_dmp_in_path:
+                shutil.copy2(_path, res_dir)
+
+    def _run_offline(self, params, res_dir, image_path):
+        """
+        Execute the dump file collection process via mounting the image.
+
+        The process includes:
+        1. Finding an available NBD device
+        2. Detecting partitions on NBD device
+        3. Determining guest type and appropriate partition
+        4. Detecting filesystem type
+        5. Mounting the partition
+        6. Processing dump files
+        7. Cleanup (unmounting and disconnecting NBD)
+
+        :param image_path: Path to the QEMU disk image.
+        :type image_path: str
+        :param res_dir: The path where results should be stored.
+        :type res_dir: str
+        :param params: Parameters of vm.
+        :type params: dict
+        """
+        # Choose the nbd device (Such as nbd15, nbd14)
+        _output = process.run(self._nbd_dev_cmd).stdout_text
+        for row in _output.strip().splitlines()[::-1]:
+            if "nbd" in row and "0B" in row and "/" not in row:
+                self._nbd_dev = row.split()[0]
+                break
+        LOG.debug("Find the available nbd device: %s", self._nbd_dev)
+
+        try:
+            qemu_nbd_cmd = "qemu-nbd -c /dev/%s %s" % (
+                self._nbd_dev,
+                image_path,
+            )
+            process.run(qemu_nbd_cmd)
+            LOG.debug("Connect the nbd device and image: %s", image_path)
+
+            # Detect the partition list (such as ["/dev/nba15p1", "/dev/nba15p2", "/dev/nba15p3"])
+            self._guest_type = params.get("os_type").lower()
+            _output = (
+                process.run("fdisk -l /dev/%s" % self._nbd_dev)
+                .stdout_text.strip()
+                .splitlines()
+            )
+            for row in _output:
+                if row.startswith("/dev/%sp" % self._nbd_dev):
+                    self._partition_list.append(row.split()[0])
+                if self._os_type_mapping[self._guest_type] in row:
+                    self._nbd_dev_partition_path = row.split()[0]
+
+            LOG.debug("Detect the nbd partition list: %s", self._partition_list)
+            LOG.debug("Detect the guest type: %s", self._guest_type)
+            LOG.debug("Detect the nbd partition path: %s", self._nbd_dev_partition_path)
+
+            # Detect the filesystem
+            self._partition_fstype = process.run(
+                "blkid -o value -s TYPE %s" % self._nbd_dev_partition_path
+            ).stdout_text.strip()
+            LOG.debug("Detect the guest fs type: %s", self._partition_fstype)
+
+            if not os.path.exists(self._mount_pt):
+                os.makedirs(self._mount_pt)
+
+            # mount the nbd device partition path
+            utils_misc.mount(
+                "%s" % self._nbd_dev_partition_path,
+                self._mount_pt,
+                fstype=self._fs_support_mapping[self._partition_fstype](),
+            )
+            self._process_dump_file_from_guest(res_dir)
+        except KeyError:
+            LOG.debug("Unsupported os_type: %s.", self._guest_type)
+        finally:
+            try:
+                utils_misc.umount(
+                    "%s" % self._nbd_dev_partition_path, self._mount_pt, None
+                )
+            except Exception as e:
+                LOG.debug("Failed to unmount: %s", e)
+
+            try:
+                process.run("qemu-nbd -d /dev/%s" % self._nbd_dev)
+            except Exception as e:
+                LOG.debug("Failed to disconnect NBD: %s", e)
+
+
+class LibvirtDumpFileManager(GuestDumpFileManager):
+    """
+    Dump file manager for libvirt virtual machines.
+
+    This class is a placeholder for future implementation of
+    dump file extraction for libvirt-managed VMs.
+    """
+
+    def __init__(self):
+        """
+        Initialize the LibvirtDumpFileManager.
+        """
+        super(LibvirtDumpFileManager, self).__init__()
+
+
+class DumpFileManagerFactory(object):
+    """
+    Factory class for creating dump file manager instances.
+
+    Implements the singleton pattern to ensure only one instance
+    of each manager type is created.
+    """
+
+    _GDF_MGR_INS = None
+
+    @classmethod
+    def get_mgr(cls, vm_type):
+        """
+        Get the dump file manager instance for the specified VM type.
+
+        :param vm_type: Type of virtual machine ("qemu" or "libvirt").
+        :type vm_type: str
+        :return: Instance of the appropriate dump file manager.
+        """
+        if not cls._GDF_MGR_INS:
+            try:
+                _type_mgr_mapping = {
+                    "qemu": QemuDumpFileManager,
+                    "libvirt": LibvirtDumpFileManager,
+                }
+                cls._GDF_MGR_INS = _type_mgr_mapping[vm_type]()
+            except KeyError:
+                LOG.debug("Unsupported vm_type: %s. Return None", vm_type)
+        return cls._GDF_MGR_INS
+
+
+def get_dump_file_mgr(vm_type):
+    """
+    Get dump file manager instance for the specified VM type.
+
+    This is a convenience function that delegates to the
+    DumpFileManagerFactory.
+
+    :param vm_type: Type of virtual machine ("qemu" or "libvirt").
+    :type vm_type: str
+    :return: Instance of the appropriate dump file manager.
+    """
+    return DumpFileManagerFactory.get_mgr(vm_type)
diff --git a/virttest/test_setup/dump_file.py b/virttest/test_setup/dump_file.py
