VMware ESXi and vSphere Cluster Management

Debug and Inspect ext File Systems with debugfs

Learn to safely inspect ext2, ext3, and ext4 metadata, extract files, and attempt deleted-file recovery with the interactive debugfs utility.

What debugfs is used for

debugfs is an interactive, low-level utility in the Linux ext filesystem toolset. It examines and, when explicitly enabled, directly manipulates metadata on ext2, ext3, and ext4 filesystems.

ext2 is a traditional Linux filesystem without journaling. ext3 adds journaling to ext2, while ext4 provides newer capacity, performance, and reliability features. A filesystem image is a file containing a block-level representation of a filesystem or storage volume. A block device is block-addressable storage, such as a disk partition or logical volume.

Typical debugfs tasks include viewing superblock and filesystem metadata, inspecting inode records, examining directories, extracting files without mounting a target, and attempting recovery of deleted files. Its information and maintenance scope overlaps in places with dumpe2fs, which displays ext filesystem information, and tune2fs, which views or adjusts selected ext filesystem parameters and features. Those utilities are not interchangeable with a complete filesystem repair tool such as e2fsck.

Safety requirements

Do not use debugfs to modify a mounted filesystem. A mounted filesystem may be changing while debugfs reads or edits its metadata, producing inconsistent results or causing further corruption. Direct metadata manipulation can also make a later recovery attempt harder.

  1. Identify the filesystem type and the exact target device or image. Use commands such as lsblk -f, blkid, and findmnt to correlate device names, UUIDs, mount points, and filesystem types.
  2. Confirm that the target is unmounted before any write-capable operation. Check all mount paths, including bind mounts and logical-volume mappings.
  3. Stop services and other processes that might write to the affected storage.
  4. Prefer a forensic image, snapshot, backup, or read-only copy. Perform recovery on the copy rather than the original whenever possible.
  5. Use a recovery destination on separate storage. Never extract a recovered file back onto the filesystem being investigated.

Normal debugfs startup is read-only unless write mode is enabled with -w. Read-only inspection is appropriate for statistics, inode examination, and planning. A write-capable session is appropriate only for a clearly defined recovery or repair procedure on an unmounted copy.

lsblk -f
findmnt
# Confirm the intended device, for example /dev/sdb2, is not mounted.

Starting and leaving a session

The basic invocation opens an ext filesystem device or image and presents an interactive prompt:

debugfs /dev/DEVICE
# Example:
debugfs /dev/sdb2

Use an image in the same way:

debugfs /cases/disk-image.ext4

For a single non-destructive query, -R runs one debugfs command and exits. It does not mean that the session is interactive; debugfs is already read-only by default unless -w is supplied.

debugfs -R 'stats' /dev/DEVICE
debugfs -R 'show_super_stats' /dev/DEVICE

At the prompt, leave cleanly with:

debugfs: quit

Viewing superblock and filesystem statistics

The superblock is core filesystem metadata describing the layout, features, counts, sizes, and state of the filesystem. At the debugfs prompt, use stats for general filesystem and superblock information. Use show_super_stats for more superblock-oriented details, including backup superblocks and block-group information where available.

debugfs: stats
debugfs: show_super_stats

Useful fields commonly include the filesystem type, block size, inode size, total and free block counts, total and free inode counts, UUID, feature flags, journal details, mount state, last mount and write times, and filesystem check information. The mount state indicates information such as whether the filesystem was last cleanly unmounted or may need attention.

These commands help verify that the selected device is the intended filesystem and provide context for health checks, capacity analysis, feature compatibility, and later use of tools such as e2fsck, dumpe2fs, or tune2fs.

Inspecting files, directories, and inodes

An inode is a filesystem metadata structure containing attributes and references to the storage used by a file or directory. An inode is not the filename itself; directory entries associate names with inode numbers.

Use stat with an internal filesystem path:

debugfs: stat /etc/hosts
debugfs: stat /var/log

The output can show the inode number, file type, permissions, owner and group IDs, link count, file size, access/change/modify times, flags, and block or extent mappings. Block mappings identify where file data is stored, while ext4 commonly represents ranges of blocks as extents.

Paths passed to debugfs refer to the filesystem that was opened, not automatically to the host system's mounted root. Use an absolute internal path when possible. You can navigate within the opened filesystem with cd and inspect the current internal directory with pwd or ls if those commands are available in the installed version.

debugfs: cd /var/log
debugfs: pwd
debugfs: ls
debugfs: stat syslog

When a path is ambiguous, begin at the filesystem root and verify each directory component. This avoids accidentally inspecting a similarly named path on the running host.

Common debugfs commands

stats / show_super_stats   Display filesystem and superblock information   Read-only inspection   Low
stat INTERNAL_PATH          Display inode metadata                         Diagnosis          Low
list_deleted_inodes         List deleted inode candidates                  Recovery planning  Low
undelete INODE NAME         Restore a deleted inode under an internal name  Recovery           High
write INTERNAL EXTERNAL     Extract an internal file to a host path        Recovery           Low
help                        List supported interactive commands            Reference          Low
quit                        Exit the session                                  Session control    Low

Risk levels describe the operation's effect on the target, not the importance of the data. Even read-only commands should be directed at the correct device or image.

Listing deleted inodes and attempting recovery

A deleted inode is an inode associated with a removed directory entry. Its metadata or data may remain recoverable until the inode or its data blocks are reused. Recovery becomes less likely as the affected filesystem receives writes.

First stop writes and unmount the target. Then open a copy in a safe session and list candidates:

debugfs /cases/ext4-copy.img
debugfs: list_deleted_inodes

Review candidate inode numbers and any available metadata, such as size, timestamps, and ownership. If a likely candidate is inode 12345, undelete restores it using a replacement name inside the opened filesystem:

debugfs: undelete 12345 /recovered/important.db

The replacement name is not a host-shell destination. It is an internal directory entry in the target filesystem. The operation may write metadata, so use an unmounted copy and understand that success is not guaranteed. The original directory name may be unavailable, and data blocks may be partly or completely reused.

After the internal file has been restored, extract it to separate host storage with write:

debugfs: write /recovered/important.db /cases/recovered/important.db

df -h /cases/recovered
ls -l /cases/recovered/important.db
file /cases/recovered/important.db
sha256sum /cases/recovered/important.db

Now the shell commands refer to the external destination on the running Linux system. Validate that the output exists, can be read, has plausible metadata and content, and matches a known-good copy when one is available. An extracted file can be empty or corrupted even when the undelete command completes.

Extracting a file without mounting the target

The write command copies a file from the opened filesystem to a path outside it:

debugfs /cases/ext4-copy.img
debugfs: write /home/alex/report.txt /cases/recovered/report.txt
debugfs: quit

ls -l /cases/recovered/report.txt
file /cases/recovered/report.txt

The first argument is the source path inside the debugfs target. The second is the destination path on the host, normally on a separate writable filesystem. This is useful in incident response, malware investigation, and recovery when mounting the affected filesystem could alter state, trigger services, or expose damaged metadata to normal filesystem operations.

Discovering commands

Use help at the prompt to list commands supported by the installed debugfs version:

debugfs: help

Some commands resemble ordinary shell or file-management commands, but they operate against the filesystem target opened by debugfs rather than against the host's current directory. Commands that create, remove, link, rename, or otherwise change files and directories require a clear recovery or repair plan. Consult the local command help and verify every path before using them.

Filesystem-specific tool selection

ext2  - debugfs /dev/DEVICE
ext3  - debugfs /dev/DEVICE
ext4  - debugfs /dev/DEVICE
XFS   - xfs_db /dev/DEVICE

debugfs is intended for the ext family, not XFS. For an XFS filesystem, xfs_db is the comparable interactive low-level utility. xfs_db supports diagnostic inspection and carefully controlled low-level manipulation of XFS metadata; it is not a general-purpose replacement for normal XFS administration or repair tools. Open the correct device and use its help facility to discover commands supported by the installed version.

xfs_db /dev/DEVICE
xfs_db> help

Always determine the filesystem type before selecting a debugging utility. Using an ext tool on XFS, or vice versa, is the wrong approach and can lead to misleading diagnostics or unsafe actions.

Practical workflow: inspect an unmounted ext4 partition

  1. Confirm the partition, UUID, and filesystem type with lsblk -f or blkid.
  2. Confirm it is not mounted with findmnt and stop processes that could write to it.
  3. Open it in the default read-only mode: debugfs /dev/sdb2.
  4. Run stats or show_super_stats.
  5. Review the filesystem features, block size, UUID, inode counts, free-space counts, and mount state.
  6. Exit with quit.

Practical workflow: inspect a suspected damaged file

  1. Open the correct device or image.
  2. Navigate to the relevant internal directory with cd, if necessary.
  3. Use stat INTERNAL_PATH to inspect the inode.
  4. Compare file type, owner, permissions, timestamps, link count, size, and block or extent references with expected values.
  5. If the file must be preserved, use write to extract it to separate storage before further investigation.

Troubleshooting

debugfs reports that the filesystem is mounted or access is refused

The target may still be mounted, or the path you selected may not be the actual backing device. Check active mounts and device relationships with findmnt and lsblk. Resolve logical-volume, encrypted-mapping, and multipath layers before proceeding. Unmount the target before write-capable work; use read-only inspection only when operational constraints make that unavoidable.

The deleted file is not listed

The inode or data blocks may already have been reused, the deletion may be too old for useful metadata to remain, or the removal may not leave a usable candidate. Stop writes, work from an image or backup, and use specialized recovery methods when debugfs cannot locate a suitable inode.

The recovered file is empty, damaged, or unexpectedly named

The original directory entry may be gone, and some file blocks may have been reused. Restore under a new internal name, inspect the inode with stat, extract it with write, and validate the external copy. Compare it with backups or known file signatures where possible.

The extracted file cannot be found on the host

Check that the external destination was an absolute, writable path on separate storage. Confirm permissions, available space, and the exact path supplied to write. Verify the output after leaving debugfs with ls, file, or a checksum command.

Safety checklist

Check                              Why it matters                         How to verify
Target is unmounted                Prevents concurrent metadata changes   findmnt, then inspect mount points
Correct device or image identified Avoids inspecting or altering another disk lsblk -f, blkid, UUID comparison
Backup or forensic image exists    Preserves an untouched recovery source  Verify image or backup before work
Separate recovery destination      Prevents overwriting recoverable blocks Choose another filesystem
Writes have stopped                Reduces inode and block reuse           Stop services and unmount target

Exam-relevant notes

  • debugfs is for ext2, ext3, and ext4; XFS uses xfs_db.
  • debugfs is read-only by default. -w enables write-capable operations.
  • -R executes one command and exits; it is not the same as an interactive session.
  • stat reports inode metadata, while stats and show_super_stats report filesystem and superblock information.
  • undelete uses an inode number and an internal replacement name. Use write afterward to copy that internal file to an external host path.
  • Deleted-file recovery depends on the inode and data blocks not having been reused.