Linux online course

Inspect and Recover ext File Systems with debugfs

Learn to safely use Linux debugfs to inspect ext2, ext3, and ext4 metadata, extract files from unmounted volumes, and investigate deleted inodes.

debugfs is an interactive, low-level utility for examining ext2, ext3, and ext4 file systems. It works directly with a block device or file-system image, rather than through a normally mounted directory tree.

This makes it useful for diagnostics and carefully controlled recovery work: you can inspect superblocks and inodes, list possible deleted files, and retrieve data without mounting the target. It also makes debugfs dangerous. A mistaken device selection or metadata edit can permanently damage the file system.

What debugfs Does

A mounted file system presents ordinary paths such as /etc/app.conf to shell commands such as ls, cp, and stat. debugfs bypasses that normal interface and reads the internal ext file-system structures directly from a device or image.

Its common uses include:

• Inspecting the superblock, feature flags, block size, UUID, and clean or dirty state.
• Examining inode metadata for files and directories.
• Listing candidate deleted inodes.
• Extracting a file from an unmounted file system when mounting is undesirable or impossible.
• Performing specialized low-level changes when a controlled repair or forensic workflow requires them.

debugfs overlaps with dumpe2fs for reporting ext metadata and with tune2fs for viewing or adjusting selected file-system parameters. debugfs is more direct and potentially more hazardous. It is not a replacement for e2fsck, the normal ext2/ext3/ext4 consistency-check and repair utility.

Safety Before Opening a Target

A block device is a device representation of storage, such as a partition, that can contain a file system. A file-system image is a regular file containing a byte-for-byte or structured representation of a file system. Either can be supplied to debugfs.

1. Identify the exact partition, logical volume, or image. Do not guess based on a device name.
2. Confirm the file system type and mount point.
3. Prefer a verified backup, clone, snapshot, or read-only image for investigation.
4. Ensure the target is unmounted before low-level inspection, and especially before any operation that might change metadata or content.
5. Use read-only operation for examination.

lsblk -f
findmnt /dev/DEVICE

lsblk -f shows file-system types, labels, UUIDs, and mount points. findmnt helps determine whether a particular device is currently mounted. A desktop environment, service, container, virtual machine, or logical-volume stack may keep a device active even when no terminal appears to be using it.

The normal debugfs mode is read-only unless writable mode is explicitly requested. Do not use debugfs -w on an original volume merely to experiment. A file system that is dirty, damaged, or suspected of corruption should generally be preserved and assessed with the appropriate checking and recovery workflow rather than edited casually.

Starting an Interactive Session

The general form is:

debugfs /dev/DEVICE
debugfs /path/to/filesystem.img

For examination, open the device or image without -w. debugfs displays a prompt, commonly similar to debugfs:. Commands entered there are debugfs commands, not normal shell commands.

debugfs /dev/DEVICE
debugfs: help
debugfs: stats
debugfs: quit

Use help to list commands. Depending on the installed e2fsprogs version, command-specific help may be available through forms such as help stat; verify the exact syntax with the built-in help. Use quit to leave the session.

For a single read-oriented query, use -R:

debugfs -R 'stats' /dev/DEVICE
debugfs -R 'show_super_stats' /dev/DEVICE
debugfs -R 'stat /internal/path' /dev/DEVICE

Viewing Superblock and File-System Information

The superblock is core file-system metadata describing the layout, size, identity, features, and state of an ext file system. At the prompt, use:

debugfs: stats
debugfs: show_super_stats

stats provides high-level information. show_super_stats displays more detailed superblock and block-group information. The exact formatting varies by e2fsprogs version.

Administrators can obtain much of this reporting with dumpe2fs. debugfs is useful when the next step is interactive inspection of a particular inode or directory.

Inodes, Paths, and Directories

An inode is a metadata record for a file or directory. It contains ownership, permissions, timestamps, size, link information, and references to the blocks containing file data. A directory entry maps a filename to an inode number; the filename itself is not the complete file record.

Use stat to inspect a path inside the target file system:

debugfs /dev/DEVICE
debugfs: stat /etc/example.conf
debugfs: stat /home/alex/report.txt

The path supplied to debugfs is an internal path. It is resolved inside the inspected device or image, not in the host system running debugfs. If the path is uncertain, directory-navigation commands such as cd and ls may be available:

debugfs: cd /etc
debugfs: ls
debugfs: stat example.conf

Supported shell-like commands and their behavior can vary by version, so consult help. The output from stat can reveal an inode number, file type, mode bits, owner and group, timestamps, file size, link count, and block mapping. These details help diagnose missing files, unexpected ownership, truncated content, and directory or allocation problems.

Inspecting an Unmounted ext4 Partition

Suppose /dev/DEVICE is the verified, unmounted ext4 partition. A safe metadata inspection looks like this:

lsblk -f
findmnt /dev/DEVICE
DEBUGFS_PAGER=cat debugfs -R 'stats' /dev/DEVICE
debugfs -R 'show_super_stats' /dev/DEVICE

Review the reported type, UUID, label, block size, feature flags, counts, mount information, and clean or dirty state. If the values do not match the expected volume, stop and recheck the device selection. The final command exits after the query; an interactive session can instead be closed with quit.

Extracting a File Without Mounting

Recovery sometimes requires copying a configuration file, log, or user document from an unmounted image. Keep the two paths distinct:

• The source is an internal path, such as /etc/example.conf, inside the ext file system.
• The destination is a host path, such as /safe/recovery/example.conf, on the running Linux system.

In standard e2fsprogs debugfs, dump is the command intended to export an internal file to a host destination:

debugfs -R 'dump /etc/example.conf /safe/recovery/example.conf' /path/to/filesystem.img
stat /safe/recovery/example.conf
wc -c /safe/recovery/example.conf
sed -n '1,20p' /safe/recovery/example.conf

Some command references incorrectly describe write as the extraction command. In standard debugfs, write generally copies a host-side file into the target file system, which is a modifying operation. Confirm the direction in your version with help write; do not use it for extraction unless that version explicitly documents the requested behavior.

After exporting, check that the destination exists, has the expected size, and contains plausible content. Exported data does not automatically preserve all original ownership, permissions, extended attributes, or other metadata, so validate those separately when they matter.

Investigating Deleted Files

A deleted inode is an inode associated with a removed file that may still contain metadata or data references. It is not a guarantee that the file can be restored.

Perform the investigation on a clone or image:

debugfs /path/to/working-copy.img
debugfs: list_deleted_inodes
debugfs: stat <INODE_NUMBER>
debugfs: quit

Inspect a candidate before attempting restoration. Check its size, timestamps, type, block mapping, and other metadata. If the evidence is credible, the conceptual restoration command is:

debugfs -w /path/to/working-copy.img
debugfs: undelete <INODE_NUMBER> restored-name
debugfs: quit

undelete is a high-risk, modifying operation. Use it only on a copy, and treat the result as untrusted until validated. Data blocks may have been reused, directory entries may no longer map cleanly to the inode, journal activity may change what remains discoverable, and solid-state storage discard behavior may remove recoverable data. Minimize writes to the affected original volume before imaging it.

Validate a recovered file by examining its size, file type, expected structure, checksums where available, and application-level readability. A restored name and inode do not prove that every data block is intact.

Common debugfs Commands

Recovery Command Risks and Precautions

Choosing the Correct File-System Tool

Tools must match the file-system family. debugfs is for ext2, ext3, and ext4; it is not the interactive debugging utility for XFS.

For an XFS target, first identify the type, then use the appropriate tool:

lsblk -f
xfs_db /dev/DEVICE

Do not apply ext-specific debugfs procedures to XFS. Likewise, do not treat debugfs as a general replacement for e2fsck; inspection and consistency repair are different tasks.

Troubleshooting

debugfs reports an invalid or unsupported file system

• Verify the target with lsblk -f or blkid.
• Confirm that you selected the partition or image containing the file system, rather than the entire disk or a partition table.
• If the type is XFS, use xfs_db and XFS-specific checking tools.
• If the target should be ext but appears severely damaged, preserve it and use an appropriate imaging and checking workflow.

The target is still mounted

• Check with findmnt and lsblk.
• Find services, containers, virtual machines, or automount processes using the device.
• Unmount it cleanly before low-level modification. If that is not possible, work from a snapshot, clone, or image.

A deleted file is missing or corrupted

The inode or data blocks may have been reused. Directory information may be gone, journal activity may have changed the metadata, or SSD discard may have eliminated the old blocks. Stop using the original volume, work from a copy, inspect candidate inodes, and expect that recovery may be partial or impossible.

write cannot extract a requested file

In standard debugfs, this usually reflects a mistaken command direction: write imports a host file into the file system. Use help write to verify the installed version and use dump for standard host-side extraction. Also confirm the internal path with directory listing and stat, then check host-side permissions and free space.

Superblock information is inconsistent or unclean

An unexpected shutdown, pending journal recovery, corruption, or a wrong target can produce these symptoms. Preserve the volume or create an image before repair attempts. For ext file systems, use the appropriate e2fsck procedure rather than making speculative metadata edits in debugfs.

Recommended Investigation Workflow

1. Identify the device or image and confirm its file-system type.
2. Check the mount state and stop unnecessary writes.
3. Create or select a verified backup, clone, snapshot, or read-only image.
4. Run read-only metadata queries such as stats and show_super_stats.
5. Inspect relevant paths and inodes with stat.
6. Extract needed files to a separate host-side destination, preferably with dump.
7. For deleted-file work, list and inspect candidates on the copy before considering undelete.
8. Validate recovered content before relying on it.
9. Use e2fsck or another file-system-specific repair workflow when consistency checking is required.

For broader Linux device, mount, and administration topics, see Linux lessons.