Inspect an ext4 Image Safely with debugfs

You will use debugfs to inspect an ext2, ext3 or ext4 filesystem image without mounting it, find files by path or inode, inspect their metadata, and copy file contents out for analysis. The examples use a disposable image, but the same read-only commands work against a real image or block device.

Allow about 15 minutes for a basic inspection. You need the debugfs command from e2fsprogs. The installed system used for these examples has e2fsprogs and debugfs version 1.47.0. On a real block device, reading it may require elevated privileges. Do not use a mounted filesystem as a write target for repair work.

Checkpoint 1: keep the filesystem read-only

Start by identifying the command version and choosing the image or device. With no -w option, debugfs opens the filesystem read-only. That is the safe default.

debugfs -V
sudo debugfs /dev/DEVICE

Replace /dev/DEVICE with a filesystem device such as /dev/nvme0n1p2. The sudo is only needed when your account cannot read the device. If you are examining a regular image file that you own, omit it:

debugfs /path/to/filesystem.img

The prompt normally changes to debugfs:. At that prompt, commands such as stats, ls, stat and blocks inspect structures. Type quit when finished.

For a non-interactive check, use -R. It runs one debugfs request and exits, which is easier to record in a script:

sudo debugfs -R 'stats' /dev/DEVICE

Look for the filesystem magic number, feature list and state in the output. A healthy image commonly reports Filesystem magic number: 0xEF53 and Filesystem state: clean. Those fields are evidence about the metadata, not a substitute for a full filesystem check.

Checkpoint 2: inspect the root and identify an inode

Use ls to list a directory. A leading slash makes a path relative to the filesystem root, rather than to debugfs's current directory.

debugfs -R 'ls -l /' /path/to/filesystem.img
debugfs -R 'ls -l /etc' /path/to/filesystem.img

The long listing includes inode numbers. You can refer to a file either by its pathname or by putting an inode number in angle brackets, for example <2> for the conventional root inode. The angle brackets are part of the debugfs filespec syntax.

Once you have a path, ask for its inode details:

debugfs -R 'stat /etc/hostname' /path/to/filesystem.img
debugfs -R 'stat <INODE_NUMBER>' /path/to/filesystem.img

Replace INODE_NUMBER with digits from the listing. The response shows the inode type, permissions, ownership, timestamps, size and allocated blocks or extents. If a path is not found, first list its parent directory and check spelling. A relative filespec depends on debugfs's current directory; using an absolute filesystem path avoids that distraction.

Checkpoint 3: read or extract a file

For a small text file, cat sends the inode contents to standard output. This does not invoke the host system's path lookup or mount the image.

debugfs -R 'cat /etc/hostname' /path/to/filesystem.img

For binary data or a file that should be preserved, use dump and an output path on the host filesystem:

debugfs -R 'dump /path/in/image /tmp/recovered-file' /path/to/filesystem.img
file /tmp/recovered-file

The destination is an ordinary host path. debugfs does not create missing parent directories. Choose an output directory with enough free space and do not accidentally point it at an important existing file. The -p option to the debugfs dump command copies ownership, group and permissions metadata to the output file where possible; leave it out when you only need the bytes.

Check that extraction produced the expected size before analysing it:

debugfs -R 'stat /path/in/image' /path/to/filesystem.img
stat -c '%n %s bytes' /tmp/recovered-file

Checkpoint 4: trace blocks when the problem is lower-level

When an inode looks suspicious, blocks prints the filesystem blocks it uses. imap instead reports where the inode structure itself lives in the inode table.

debugfs -R 'blocks /path/in/image' /path/to/filesystem.img
debugfs -R 'imap /path/in/image' /path/to/filesystem.img
debugfs -R 'dump_extents /path/in/image' /path/to/filesystem.img

On an ext4 file, extent output is often more useful than a simple block list. The manual warns that ranges shown for the last extent in an interior node can be estimates from the extents library, not stored values. Treat that part as diagnostic output, not as proof that the filesystem is corrupt.

To inspect raw bytes, use block_dump with a block number obtained from the earlier output:

debugfs -R 'block_dump BLOCK_NUMBER' /path/to/filesystem.img

Replace BLOCK_NUMBER with digits only. Do not guess a block number on a valuable device. Raw output is easy to misread and tells you nothing about whether changing that block would be safe.

Commands that can change or destroy data

Several debugfs commands are editing tools, not harmless queries. The -w startup option opens the filesystem read-write. Commands such as clri, kill_file, freeb, freei, ea_set, ea_rm, mkdir, ln and feature can alter metadata or make files inaccessible. Journal commands can also write or replay transactions. Do not paste these into an investigation session.

There is no general undo command. The -z UNDO_FILE option records old filesystem blocks before debugfs overwrites them, and the resulting file can be used with e2undo. It cannot recover from a power loss or system crash, so it is not a replacement for a verified image backup. If a write is genuinely required, unmount the filesystem, make a block-level backup, use a new undo file on separate storage, and record the exact commands.

The -n option disables metadata checksum verification and should be reserved for a specific diagnostic reason. The -c option opens in catastrophic mode, skips initially reading inode and group bitmaps, and forces read-only access. These options change how damaged metadata is handled; they do not repair it. Use e2fsck according to its own documentation for filesystem repair, preferably on a copy.

Common failure modes

• "Bad magic number" or an unreadable device: confirm that the path identifies the filesystem itself, not a partition table, encrypted container or mounted subvolume. Check the device with the appropriate storage inspection tools before trying another debugfs option.
• A command reports an invalid filespec: run ls -l /, then inspect the parent directory. Use an absolute path or an inode such as <12345>.
• Output appears truncated or binary: use dump rather than cat, and inspect the copied file with tools suited to its format.
• The image is an e2image file: the -i mode contains selected metadata rather than a complete filesystem. Many commands cannot work unless you also supply the original data source with -d; debugfs has few safety checks in this mode.

Done means

• You recorded the local debugfs version.
• You opened the target without -w and confirmed its filesystem metadata.
• You identified the target inode with ls and stat.
• You extracted any required file to a deliberate host path and verified its size.
• You kept editing, journal and repair commands out of the read-only investigation.