The zgetdump tool

The source dump can be located either on a dump device or on a file system. The source dump content is written to standard output, unless you redirect it to a specific file. You can also mount the dump content, print dump information, check whether a stand-alone dump device contains a valid dump tool, or create a nondisruptive kernel dump on a live system.

The zgetdump tool automatically decompresses compressed CCW-type DASD dumps.

Parameters

<dump>

is the file, DASD device or partition, multipath partition of a SCSI disk, channel-attached tape device, or live system device node where the source dump is located:

• Regular dump file (for example /testdir/dump.0)
• DASD partition device node (for example /dev/dasdc1)
• DASD device node for multi-volume dump (for example /dev/dasdc)
• Device mapper multipath partition device node of a SCSI disk (for example /dev/mapper/36005076303ffd40100000000000020c0-part1)
• Device node for an NVMe partition (for example, /dev/nvme0n1p1).
• Tape device node (for example /dev/ntibm0)
• Device node for live system (/dev/mem)
• A dump file that is created with the z/VM® CP VMDUMP command, see Using VMDUMP.

Note: For a DASD multi-volume dump it is sufficient to specify only one of the multi-volume DASDs as <dump>.

-s <system> or --select <system>

for dumps that capture two systems, selects the system of interest. To check whether a dump contains two systems, use zgetdump -i. The -s option is mandatory when accessing the dump of a crashed kdump instance, but returns an error if applied to a regular dump.

A dump can contain data for a crashed production system and for a crashed kdump system. A dump like this is created if a stand-alone dump tool is used to create a dump for a kdump instance that crashed while creating a dump for a previously crashed production system. <system> can be:

prod

to select the data for the crashed production system.

kdump

to select the data for the kdump instance that crashed while creating a dump for the previously crashed production system.

all

to select the data for both prod and kdump.

-f <format> or --fmt <format>

Uses the specified target dump format <format> when writing or mounting the dump. The following target dump formats are supported:

elf

Executable and Linking Format core dump (default)

s390

S/390® dump

-k <key> or --key <key>

Applies only to the encrypted dumps of KVM guests in IBM® Secure Execution mode, see Working with dumps of KVM guests in IBM Secure Execution mode. <key> specifies a file with the decryption key.

<dump_file>

Is a file to which the output is written. If no file is specified, the output is written to stdout.

Note: You can now directly write the command output to a file, or you can use the former method of redirecting the output from stdout to a file.

-m <dump> <dir> or --mount <dump> <dir>

Mounts the source dump <dump> to mount point <dir> and generates a virtual target dump file instead of writing the content to standard output. The virtual dump file is named <dump>.<FMT>, where <FMT> is the name of the specified dump format (see the --fmt option).

-u <dir> or --umount <dir>

Unmounts the dump that is mounted at mount point <dir>. You can specify the dump itself instead of the directory, for example /dev/dasdd1. This option is a wrapper for fusermount -u.

-i <dump> or --info <dump>

Displays the dump header information from the dump and performs a validity check.

-V or --verbose

Shows the detailed memory-map layout when printing the dump header information for s390 (s390_ext) and ELF dump formats.

-d <dump_device> or --device <dump_device>

checks whether the specified ECKD™, FBA, SCSI disk, or NVMe disk device contains a valid dump tool and prints information about it.

<dumpdevice> can be the device node of a DASD device (for example /dev/dasdb), an NVMe disk device node (for example, /dev/nvme0n1), or a multipath device node of a SCSI disk (for example, /dev/mapper/36005076303ffd40100000000000020c0-part1).

-h or --help

Displays the help information for the command.

-v or --version

Displays the version information for the command.

Working with dumps of KVM guests in IBM Secure Execution mode

Secure images can be built to support encrypted dumps with virsh dump. A cryptographic key, the customer communication key, must then be specified with the command that builds the image (genprotimg). You need this key to read the dump of a secure guest. For more information, see Using virsh dump to create dumps on KVM hosts.

In the following examples, se-dump.elf is a file with an encrypted dump and cck is the file with the required key. Both files are in the current working directory.

• Use the zgetdump -i option to confirm that se-dump.elf is a valid dump.

  # zgetdump -i se-dump.elf 
  General dump info:
    Dump format........: ELF (protected virtualization dump)
    System arch........: s390x (64 bit)
  
  zgetdump: No key for dump decryption provided.
  Try 'zgetdump --help' for more information.
   

  The (protected virtualization dump) in the output confirms that the dump is for a KVM guest in IBM Secure Execution mode.
• Specify the key to display more information.

  # zgetdump -i se-dump.elf --key cck
  General dump info:
    Dump format........: ELF (protected virtualization dump)
    Version............: 1
    UTS node name......: lnxlp05
    UTS kernel release.: 6.6.0
    UTS kernel version.: #5 SMP Wed Oct 25 13:47:57 UTC 2023
    System arch........: s390x (64 bit)
    CPU count (online).: 2
    Dump memory range..: 1024 MB
  
  Memory map:
    0000000000000000 - 000000003fffffff (1024 MB)
   

• You can create a decrypted copy of the dump file, and then proceed working with the decrypted version.

  # zgetdump se-dump.elf se-dump.decrypted.elf --key cck

  Protect the decrypted dump from unauthorized access.
• As an alternative to creating a decrypted dump file, you can mount the dump. A mounted dump is decrypted incrementally, as it is accessed. Especially for large dumps, this method can be advantageous over first creating a decrypted copy of the dump file. In the example, the mount point is a directory /dumps in the file system.

  # zgetdump -m se-dump.elf /dumps --key cck

  Analyze the mounted dump with crash, as usual.

  # crash vmlinux /dumps/dump.elf

  Unmount the dump when you have completed your work.

  # zgetdump -u /dumps