btrfs-inspect-internal

Print superblock's information

$ sudo btrfs inspect-internal dump-super [path/to/partition]

$ sudo btrfs inspect-internal dump-super [[-a|--all]] [path/to/partition]

$ sudo btrfs inspect-internal dump-tree [path/to/partition]

$ sudo btrfs inspect-internal inode-resolve [n] [path/to/btrfs_mount]

$ sudo btrfs inspect-internal logical-resolve [logical_address] [path/to/btrfs_mount]

$ sudo btrfs inspect-internal tree-stats [path/to/partition]

btrfs-inspect-internal [options] <device>

--super
    Dumps the content of the superblocks found on the device.

--root <root_id>
    Dumps the content of the B-tree for the specified root ID. This is typically used for subvolume roots.

--chunk-tree
    Dumps the internal structure of the chunk tree, showing block groups and their properties.

--extent-tree
    Dumps the internal structure of the extent tree, showing extent allocation and references.

--dump-full-inodes
    When used with --root, dumps full inode items instead of summary information.

--dump-extents
    When used with --root, dumps detailed extent information for files and directories.

--dump-block-group
    Dumps detailed information about block group items.

--dump-root-tree
    Dumps the internal structure of the root tree, which tracks all subvolumes and snapshots.

--raw
    Outputs data in a raw, unformatted binary or hexadecimal form for some options.

<device>
    The Btrfs device or image file to inspect. This is a mandatory argument.

btrfs-inspect-internal is a low-level, developer-oriented tool designed for examining the internal structures of a Btrfs filesystem. Unlike standard btrfs commands that operate at a higher abstraction level, this command directly interprets the on-disk format, allowing users to delve into the raw metadata and B-tree structures. It is primarily used for debugging, forensic analysis, and understanding the intricate details of how Btrfs stores its data, metadata, and performs operations. It can display information about superblocks, chunk trees, root trees, extent trees, checksums, and other critical internal components. It's an invaluable tool for Btrfs developers and advanced users needing to diagnose filesystem corruption or understand the underlying mechanics that govern Btrfs. It should be used with extreme caution, as misinterpreting its output can lead to incorrect conclusions or even data loss if external tools are used based on such interpretations. It is not intended for routine filesystem management.

This command is a low-level, developer-oriented tool and is not intended for casual use or routine filesystem administration. Its output is highly technical and requires a deep understanding of Btrfs internal structures to interpret correctly. The output format can change between Btrfs versions, potentially making scripts or expectations fragile. While btrfs-inspect-internal itself is primarily a read-only tool, misinterpreting its output can lead to incorrect diagnostic conclusions or dangerous actions if used in conjunction with other tools for recovery or manipulation.

It is generally recommended to use btrfs-inspect-internal on an unmounted Btrfs device or a disk image to ensure consistency and prevent any potential conflicts with a live filesystem. While primarily read-only, direct device access on a live filesystem can sometimes have unexpected side effects or lead to inconsistent output. Root privileges are typically required to access raw device files.

This command is an indispensable tool for Btrfs developers and advanced system administrators engaged in forensic analysis or debugging severe filesystem corruption. By providing a direct view of the B-tree structures, it helps in understanding the state of metadata, identifying corrupted nodes, and tracing the allocation of data and metadata blocks.

btrfs-inspect-internal has been a core debugging and development utility within the btrfs-progs suite since the early stages of Btrfs filesystem development. Its purpose has remained consistent: to provide direct, low-level access to the on-disk Btrfs structures for developers and advanced users. As the Btrfs filesystem format and features have evolved, so too have the capabilities and specific output formats of this tool to reflect the changes in B-tree structures, item types, and metadata organization.

btrfs(8), btrfs-check(8)