btrfs-inspect-internal
Inspect internal Btrfs filesystem data structures
TLDR
Print superblock's information
Print superblock's and all of its copies' information
Print filesystem's metadata information
Print list of files in inode n-th
Print list of files at a given logical address
Print stats of root, extent, csum and fs trees
SYNOPSIS
btrfs-inspect-internal [options] <device>
PARAMETERS
--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.
DESCRIPTION
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.
CAVEATS
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.
USAGE BEST PRACTICES
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.
FORENSIC AND DEBUGGING AID
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.
HISTORY
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.
SEE ALSO
btrfs(8), btrfs-check(8)