zdb

Show detailed configuration of all mounted ZFS zpools

$ zdb

$ zdb [[-C|--config]] [poolname]

$ zdb [[-b|--block-stats]] [poolname]

zdb [options]
zdb [options]

-b
    Dump block information, including allocated and bad blocks.

-c
    Dump configuration information for the pool or vdev.

-d
    Dump specific data blocks. Can be used multiple times for increased verbosity (e.g., -ddd).

-D
    Dump DDT (Deduplication Table) statistics and information.

-e
    Suppress printing of empty entries in output.

-E
    Print errors encountered during the scan or dump.

-h
    Display the help message and exit.

-i
    Inspect vdev I/O statistics and block allocation.

-k
    Dump kernel-level ZFS statistics (on supported systems).

-L
    Look up a specific ZFS object by its ID.

-m
    Dump the contents of the MOS (Meta Object Set).

-o
    Specify a specific object ID to inspect (often used with -L or -d).

-P
    Dump pathname information for objects.

-s
    Summarize space usage per block type within the pool.

-U
    Dump the unallocated space map.

-v
    Increase verbosity of output. Can be used with other flags.

-X
    Examine a specific uberblock by its ID.

zdb (ZFS Debugger) is a powerful, low-level diagnostic tool designed to examine the internal on-disk structure of a ZFS storage pool or dataset. Unlike zpool or zfs which provide high-level management and reporting, zdb delves into the raw metadata and data blocks, allowing administrators and developers to inspect block pointers, DDTs (deduplication tables), MOS (Meta Object Set), space maps, and other core components.

It's primarily used for deep-dive debugging, understanding ZFS internals, and in rare cases, aiding in data recovery or corruption analysis when standard tools are insufficient. Its output is highly verbose and requires a detailed understanding of ZFS architecture. It operates in a read-only mode, ensuring no modifications are made to the pool.

zdb requires deep knowledge of ZFS internals for effective use. Its output is extremely verbose and complex, making it unsuitable for casual or routine administration.

While it operates in a read-only mode, misinterpretation of its diagnostic output could lead to incorrect assumptions or recovery attempts if not handled by experienced users or ZFS experts.

Diagnosing Corruption: When zpool scrub or zpool status report errors that are hard to diagnose, zdb can provide detailed insights into the corrupted blocks or metadata.

Understanding Space Usage: Options like zdb -s and zdb -U help in understanding how space is allocated and what types of blocks consume space.

Deep Dive Debugging: For ZFS developers or system administrators troubleshooting highly complex issues, zdb allows direct inspection of on-disk structures, crucial for understanding specific bugs or recovery scenarios.

The output of zdb is highly specialized and often involves hexadecimal addresses, block pointers, and internal ZFS object IDs.

Understanding requires familiarity with ZFS concepts like Data Management Units (DMU), ZIO pipeline, block pointers, copy-on-write, uberblocks, and the Meta Object Set (MOS).

It's often used in conjunction with ZFS source code or detailed architectural documentation for full comprehension.

ZFS (Zettabyte File System) was originally developed by Sun Microsystems for Solaris, designed for large-scale data storage and integrity. zdb was an integral part of the ZFS suite from its early days, providing the necessary low-level introspection capabilities for development, debugging, and post-mortem analysis.

With the open-sourcing of ZFS (OpenZFS), zdb continued its role as a critical diagnostic utility, evolving alongside the filesystem itself to support new features and address complex data integrity issues across various platforms like Linux, FreeBSD, and macOS. Its design reflects the robust, self-healing, and diagnostic-friendly nature of ZFS.

zpool(8), zfs(8), arcstat(1), kstat(1)