20.19. Creating a Dump File of a Guest Virtual Machine's Core Using virsh dump

One of the methods of troubleshooting guest virtual machines (in addition to kdump and pvpanic) is using the virsh dump domain corefilepath [--bypass-cache] {--live | --crash | --reset} [--verbose] [--memory-only] [--format=format] command. This creates a dump file containing the core of the guest virtual machine so that it can be analyzed, for example by the crash utility.
Specifically, running virsh dump command dumps the guest virtual machine core to a file specified by the core file path that you supply. Note that some hypervisors may give restrictions on this action and may require the user to manually ensure proper permissions on the file and path specified in the corefilepath parameter. This command is supported with SR-IOV devices as well as other passthrough devices. The following arguments are supported and have the following effect:
  • --bypass-cache - The file saved will not bypass the host's file system cache. It has no effect on the content of the file. Note that selecting this option may slow down the dump operation.
  • --live will save the file as the guest virtual machine continues to run and will not pause or stop the guest virtual machine.
  • --crash puts the guest virtual machine in a crashed status rather than leaving it in a paused state while the dump file is saved. The guest virtual machine will be listed as "Shut off", with the reason as "Crashed".
  • --reset - When the dump file is successfully saved, the guest virtual machine will reset.
  • --verbose displays the progress of the dump process
  • --memory-only - Running a dump using this option will create a dump file where the contents of the dump file will only contain the guest virtual machine's memory and CPU common register file. This option should be used in cases where running a full dump will fail. This may happen when a guest virtual machine cannot be live migrated (due to a passthrough PCI device).
    You can save the memory-only dump using the --format=format option. The following formats are available:
    • elf - the default, uncompressed format
    • kdump-zlib - kdump-compressed format with zlib compression
    • kdump-lzo - kdump-compressed format with LZO compression
    • kdump-snappy - kdump-compressed format with Snappy compression

    Important

    The crash utility no longer supports the default core dump file format of the virsh dump command. If you use crash to analyze to core dump file created by virsh dump, you must use the --memory-only option.
Note that the entire process can be monitored using the virsh domjobinfo command and can be canceled using the virsh domjobabort command.

Example 20.47. How to create a dump file with virsh

The following example creates a dump file of the guest1 virtual machine's core, saves it into the core/file/path.file file, and then resets the guest. The most common scenario for using this command is if your guest virtual machine is not behaving properly: 
# virsh dump guest1 core/file/path.file --reset