Using virsh dump to create dumps on KVM hosts

The virsh dump command writes KVM guest dumps to a file in the KVM host file system.

About this task

Use virsh dump as an alternative or as a backup method for creating dumps of KVM guests with kdump.

The virsh dump command is installed with the libvirt package on the KVM host. Apart from setting aside a host directory with sufficient storage space to hold the dumps, no special preparation is needed.

You can use virsh dump to create dumps of both running or crashed KVM guests. By default, virsh dump pauses a running guest during the dump process. If all is well, the guest continues running when the dump is complete, but lengthy pausing might result in a malfunctioning guest. For example, a large guest memory or the encryption associated with a guest in IBM® Secure Execution mode can lead to excessive pausing.

For more information about KVM guests, KVM virtual servers, and virsh commands, see KVM Virtual Server Management, SC34-2752.

Procedure

On the KVM host, issue a virsh dump command with the --memory-only option to create a dump.

# virsh dump --memory-only [<mode>] <virtual_server> <dump_file>

where

--memory-only

writes the dump file in a valid elf format as required by the crash tool.

<mode>

Optional: specifies one of the following dump modes.

--crash: halts the KVM guest with a crashed state before starting the dump process.
--reset: resets the virtual server when the dump process is complete.
--live: does not pause the guest during the dump process. This option can result in an inconsistent dump.

<virtual_server>

specifies the name of the virtual server on which the KVM guest runs.

<dump_file>

specifies the file to which the dump is written. If a file name without a fully qualified path is specified, the dump file is written to the current working directory from which the visrh dump command is issued.

The following example creates a dump of a Linux® instance on a virtual server vserv3 to a host file /dumps/vser3.dump1.elf.

# virsh dump vserv3 /dumps/vser3.dump1.elf --memory-only

Results

You can use makedumpfile to compress and filter the dump, and can analyze the dump with the crash tool.

For dumps of KVM guests in IBM Secure Execution mode, you must decrypt the dump with the zgetdump tool before you can compress, filter, or analyze it.

You must enable encrypted dumps when you create the secure image with the genprotimg command. This enablement requires two command options: --enable-dump and --comm-key. With the --comm-key option, you specify the customer communication key, which is required to decrypt the dump.

This example shows how a secure image is created with dumps enabled:

# genprotimg -i /boot/vmlinuz -r /boot/initrd.img -p parmfile -k HKD-8651-000201C048.crt \
--cert ibm_signkey.crt --cert digicert_intermediate.crt -o /boot/secure-linux \
--enable-dump --comm-key customer.key

Encrypted dumps for secure guests require hardware support and were introduced with IBM z16 and IBM LinuxONE Emperor 4.