ZGETDUMP(8)

📦 version 2.44.1, in opensuse-leap 16.0

💅 ZGETDUMP(8) — zgetdump, the zSystems dump bestie

okay so bestie, welcome to ZGETDUMP(8) from the System Manager's Manual. This is the page for zgetdump, aka the tool for copying and converting IBM zSystems dumps. She’s niche, she’s powerful, and she absolutely ate. Let’s get into it. 🫶

✨ NAME ✨

zgetdump — tool for copying and converting IBM zSystems dumps. 💖

✨ SYNOPSIS ✨

zgetdump    DUMP [-s SYS] [-f FMT] [-k KEY] > DUMP_FILE
            DUMP [-s SYS] [-f FMT] [-k KEY] DUMP_FILE
             -m DUMP [-s SYS] [-f FMT] [-k KEY] DIR
             -i DUMP [-s SYS] [-k KEY]
             -d DUMPDEV
             -u DIR
             -h|-v

✨ DESCRIPTION ✨

The zgetdump tool copies a source dump into a target dump with a configurable dump format. The source dump can live either on a dump device or on a file system. By default, the source dump content is written to standard output, which you can redirect to a specific file. You can also mount the dump content, print dump information, check whether a dump device contains a valid dump tool, or create a non-disruptive dump on a live system. Literally versatile. 💅

✨ OPTIONS ✨

  • -h, --help — print usage information, then exit. Short and sweet.
  • -v, --version — print version information, then exit. Also iconic.
  • -k <KEY>, --key <KEY> — specify the file KEY to use as key for the decryption of a protected virtualization dump. 🔐
  • -m <DUMP> <DIR>, --mount <DUMP> <DIR> — mount the source dump DUMP to mount point DIR and generate a virtual target dump file instead of writing the content to standard output. The virtual dump file gets the name dump.FMT, where FMT is the name of the specified dump format (see the --fmt option). 🧚
  • -u <DIR>, --umount <DIR> — unmount the dump that is mounted at mount point DIR. This option is a wrapper for fusermount -u. Instead of DIR, also the DUMP (for example /dev/dasdd1) can be specified.
  • -d <DUMPDEV>, --device <DUMPDEV> — check the dump disk DUMPDEV for a valid dump tool and print information about it. See chapters DUMPDEV and DUMPDEV INFORMATION below for more information. 👀
  • -i <DUMP>, --info <DUMP> — print the dump header information reading from the DUMP and check if the dump is valid. See chapters DUMP and DUMP INFORMATION below for more information.
  • -V, --verbose — show the detailed memory map layout when printing the dump header information (relevant for s390_ext and ELF dump formats). More detail, more drama. ✨
  • -f <FMT>, --fmt <FMT> — use the specified target dump format FMT when writing or mounting the dump. The following target dump formats are supported:
    • elf: Executable and Linkable Format core dump (default). The main character.
    • s390: s390 dump.
  • -s <SYS>, --select <SYS> — if kdump fails and a stand-alone dump is created, the resulting dump captures two systems: the crashed kdump system and the previously crashed Linux instance. With the --select option you can choose which system data to use:
    • prod: Data for the initial crashed Linux instance.
    • kdump: Data for the crashed kdump system.
    • all: Data for the initial crashed Linux and kdump system.
bestie, the -s option returns an error for dumps that capture only a single crashed system. no cap.

🌀 DUMP

This parameter specifies the file, partition or tape device node where the source dump is located:

  • Regular dump file (e.g. /dumps/dump.0)
  • vmdump file (e. g. VMDUMP.FILE)
  • DASD partition device node (e.g. /dev/dasdc1)
  • DASD device node for multi-volume dump (e.g. /dev/dasdc)
  • Device mapper multipath partition device node of a FCP attached SCSI disk (e.g. /dev/mapper/3600..20c0-part1)
  • NVMe partition device node (e.g. /dev/nvme0n1p1)
  • Tape device node (e.g. /dev/ntibm0)
  • Device node for live system (/dev/mem or /dev/crash)
  • Protected virtualization dump file (e.g. /dumps/pv.elf)
🫶 note: for DASD multi-volume dump it is sufficient to specify only one of the multi-volume DASD partitions as DUMP.

🌀 DUMPDEV

When using the --device option, DUMPDEV must be the device node of the dump disk that should be verified. This can be either a DASD device node, a device mapper multipath device node of a FCP attached SCSI disk or a NVMe device node. 🕵️‍♀️

✨ COPY DUMP ✨

The default action of zgetdump is to copy the source dump to standard output in the target format specified by the --fmt option. Read the examples section below for more information. slay. 💖

✨ MOUNT DUMP ✨

Use the --mount option to make a source dump accessible to tools that cannot directly read the original dump format. Rather than creating a converted copy of the dump, zgetdump creates a virtual dump file with the requested target format. This is fast and does not consume any additional disk space. Also multi-volume dumps can be assimilated into a single virtual dump file, which can then be accessed directly with dump-processing tools like makedumpfile or crash. iconic behavior, honestly. 🌈

Specify a command of this form to mount and convert a dump:

# zgetdump --mount <DUMP> <DIR>  --fmt <FMT>

Where:

  • DUMP is the source dump or dump device.
  • DIR is the mount point where the virtual dump file is created.
  • FMT is the target dump format to which the virtual dump file is converted. The resulting virtual dump file is <DIR>/dump.<FMT>.

The virtual dump file exists until the directory is unmounted. Use zgetdump -u <DIR> to unmount a dump.

The zgetdump tool uses the file system in user space (fuse) to mount the source dump. Therefore, the fuse kernel module must be loaded before using the --mount option.

⚠️ bestie, that fuse kernel module thing is not optional. load it before you mount, fr fr.

Read the examples section below for more information.

✨ DUMP FORMATS ✨

The default target format of zgetdump is elf. Use the --fmt option to change the target format. The following dump formats are supported for target and source dump:

  • elf — Executable and Linkable Format core dump. This dump format is also used for Linux user space core dumps.
  • ELF (protected virtualization dump): Protected virtualization vmcore dump in Executable and Linkable Format.
  • s390 — This dump format is IBM zSystems specific and is used for DASD and tape dumps.

The following dump formats are supported for the source dump only:

  • s390_ext — This dump format is IBM zSystems specific and is used for DASD dumps only. Starting with s390_ext format version 2, dumps also support zlib compression.
  • vmdump — Dumps with this format are created by the z/VM vmdump command and stored in the reader device. Use the vmur tool to extract such dumps from the reader device and save them on disk.
  • lkcd — This dump format is used by the Linux Kernel Crash Dumps (LKCD) project.
  • devmem — On live systems the /dev/mem or /dev/crash device nodes can be used as source dumps for creating live dumps.
  • kdump/kdump_flat — Dump formats created by the makedumpfile tool. For these formats only the --info option can be used.

✨ DUMP INFORMATION ✨

Depending on the dump format, the following dump attributes are available when calling zgetdump with the --info option:

  • Dump format — Name of the dump format.
  • Version — Version number of the dump format.
  • Dump method — Dump method that has been used to create the dump. Currently the only supported value for this attribute is live, which indicates that the dump has been created from a live system and therefore is not consistent. 🫠
  • Dump created/ended — Time when the dump process was started or ended. The dump time information is printed in your local time zone. E.g. Wed, 03 Feb 2010 10:47:37 +0100 shows the time at your location. The meaning of +0100 is that your time zone is one hour behind GMT. You can use the TZ environment variable or use the tzselect tool to change the time zone. For example, if you know that the dump has been created in Hawaii, you can get the correct time information with:
# TZ='Pacific/Honolulu' zgetdump -i DUMP
  • Dump CPU ID — Identifier of the CPU that ran the dump tool.
  • UTS node name — The network node hostname of the Linux system.
  • UTS kernel release — The kernel release of the Linux system.
  • UTS kernel version — The kernel version of the Linux system.
  • System arch — Architecture of the Linux system (currently only s390x is possible).
  • CPU count (online) — Number of online CPUs.
  • CPU count (real) — Number of total CPUs (online and offline).
  • Dump memory range — Memory range that was dumped. This value is the difference between the last dumped and the first dumped memory address.
  • Real memory range — Memory range that was available on the system. This value is the difference between the last and the first memory address of the system on which the dump was created. The “real memory range” can differ from the “dump memory range” when the SIZE parameter was used when preparing the dump device with the zipl tool (see man zipl).
  • Dump file size — Actual size of dump file on disk in megabytes. “Dump file size” may differ from the “dump memory range” because of zero memory chunks or dump compression.
  • Zlib version — The version of zlib used for compressed dumps.
  • Zlib compression unit — Size of the input data chunks that has been used for the dump zlib compression by the dump tool. Every chunk of data is compressed separately and can be decompressed independently, allowing zgetdump to make fast read seeks.
  • Memory map — Available memory chunks in the dump. Some dump tools create multiple memory chunks when creating a dump on a system with memory gaps.

✨ DUMPDEV INFORMATION ✨

Okay so this section is lowkey the fun one, because depending on which dump tool you're dealing with, zgetdump with the --device option will hand you these attributes. Not every tool gives you all of them — it's giving "each tool has its own personality" 💅

  • Dump tool — the name of the dump tool. Like, its whole identity.
  • Version — the version of the dump tool. Bestie's version number, iconic.
  • Architecture — the architecture of the dump tool. And ngl, currently only s390x is possible. That's the whole list, no cap.
  • DASD type — the type of the DASD where the dump tool is installed. It's either ECKD or FBA, pick your fighter 🎀
  • Dump size limit — if this attribute is set, the dump tool will dump memory only up to that limit, even if there's literally more memory available. Boundaries! We respect them 🫶
  • Force specified — if this attribute is set to "yes", the multi-volume DASD dump tool will not verify the dump signature on dump partitions. Which is handy if the dump partition is also being used for swap. Just saying 👀
  • Partition info — for SCSI partition dump, the partition number and the maximum dump size get printed. The partition number corresponds to the output of "parted /dev/sdx print" or "fdisk -l /dev/sdx". For NVMe partition dump, the partition number is printed. That partition number corresponds to the output of "parted /dev/nvm0n1 print" or "fdisk -l /dev/nvme0n1".
  • Meta info — for NVMe partition dump, the dump file name gets printed. Cute little name reveal ✨

🌸 EXAMPLES 🌸

This is the part where we actually do stuff, so buckle up bestie, we're going shopping 🛍️

Copy single-volume DASD dump

Picture it: the DASD partition /dev/dasdx1 was prepared for dump with:

# zipl -d /dev/dasdx1

Then an IPL was performed on the corresponding single-volume dump tool, and a dump has been created. To copy the dump from the DASD partition into the file dump.elf, you literally just issue:

# zgetdump /dev/dasdx1 > dump.elf

Slay. That's it. 💅

Copy multi-volume DASD dump

So DASD partitions /dev/dasdx1 and /dev/dasdy1 contained in the file dev_list.conf were prepared for multi-volume dump with:

# zipl -M dev_list.conf

An IPL was performed on the corresponding multi-volume dump tool, and a dump has been created. To copy the dump from the DASD partitions to the file dump.elf, issue:

# zgetdump /dev/dasdx > dump.elf

Note the missing 1 at the end there — that's not a typo, that's the whole vibe of multi-volume. iykyk 🦋

Copy SCSI dump

The device mapper multipath partition on a SCSI disk /dev/mapper/3600..20c0-part1 was prepared for dump with:

# zipl -d /dev/mapper/3600..20c0-part1

An IPL was performed on the corresponding dump tool, a dump has been created, and to copy the dump from the device mapper partition to the file dump.elf you issue:

# zgetdump /dev/mapper/3600..20c0-part1 > dump.elf

That path is giving "I memorized my own IP address" energy and honestly? Respect 💀

Copy NVMe dump

The NVMe partition device node /dev/nvme0n1p1 was prepared for dump with:

# zipl -d /dev/nvme0n1p1

An IPL was performed on the corresponding dump tool and a dump has been created. To copy the dump from the NVMe partition to the file dump.elf issue:

# zgetdump /dev/nvme0n1p1 > dump.elf

Copy tape dump

Tape device /dev/ntibm0 was prepared with:

# zipl -d /dev/ntibm0

An IPL was performed on the corresponding tape dump tool, a dump has been created, and to copy the dump from the tape to the file dump.elf you issue:

# zgetdump /dev/ntibm0 > dump.elf

Tapes are honestly so retro-cool, vintage icon behavior 🎀

Create live dump

Wanna store an ELF-format dump from a live system into a file called dump.elf? Issue:

# nice -n -20 zgetdump /dev/mem > dump.elf

Yes, /dev/mem. Yes, live. Yes, nice -n -20 because we are not being polite about priority. Main character energy for real 👑

Using pipes for network transfer

You can redirect standard output to tools like ftp or ssh so you can transfer the dump over the network without copying it into the file system first. No middleman, no storage drama, we love efficiency ✨

Copy a DASD dump using ssh:

# zgetdump /dev/dasdd1  | ssh user@host "cat > dump.elf"

Copy and compress a DASD dump using ftp and gzip (heads up: not all ftp clients can do this — check before you commit, bestie):

# ftp host
ftp> put |"zgetdump /dev/dasdd1 | gzip" dump.elf.gz

The same effect can also be achieved by using the --mount option and running scp or ftp directly on the mounted virtual dump file. Multiple routes to the same slay, we stan flexibility 🌈

Using the --mount option

Mount a single-volume DASD dump as a virtual ELF dump file, compress it with the makedumpfile tool, and unmount it with zgetdump:

# zgetdump -m /dev/dasdc1 /dumps
# makedumpfile -c -d 31 -x vmlinux.debug \
     /dumps/dump.elf dump.kdump
# zgetdump -u /dumps

Now mount a multi-volume DASD dump, process it with the "crash" tool, and unmount it with fusermount:

# zgetdump -m /dev/dasdx /dumps
# crash vmlinux /dumps/dump.elf
# fusermount -u /dumps

See how the unmount tool changes at the end? Pay attention, that's the plot twist 🔥

Print information about a DASD dump on /dev/dasdd1:

# zgetdump -i /dev/dasdd1

Print information about a dump on a device mapper multipath partition device node of a SCSI disk:

# zgetdump -i /dev/mapper/3600..20c0-part1

Print information about a dump on a partition device node of a NVMe disk:

# zgetdump -i /dev/nvme0n1p1

Print information about a DASD dump tool on /dev/dasdd:

# zgetdump -d /dev/dasdd

Print information about a dump tool on a SCSI multipath device:

# zgetdump -d /dev/mapper/3600..02c0

Print information about a dump tool on a NVMe device:

# zgetdump -d /dev/nvme0n1

Notice how --info takes the partition and --device takes the whole device? That's the difference bestie, don't mix them up 😭

💀 NOTES 💀

  • The ELF dump format is not supported by the zgetdump tool under 31 bit. That's a hard no, not a vibe check.
  • While it is not recommended for reasons of recovery and redundancy, FCP attached SCSI disks can also be accessed directly without multipathing — for example via the "/dev/disk/by-path/" device nodes. Like, you can, but the manpage is literally side-eyeing you. Recovery and redundancy said "don't". 🙈

👑 SEE ALSO 👑

zipl(8), crash(8), makedumpfile(8), dumpconf(8), vmur(8) fdisk(8), parted(8)

Go read those too, they're all in the same friend group 🫶

Okay that's the whole page, you made it to the end and I'm so proud of you 🌟 This little masterpiece comes from s390-tools, dated January 2023, and the page itself is ZGETDUMP(8). Now go dump something responsibly, mwah 💖

📦 where this page comes from