Inspect an ext4 Image Safely with debugfs

You can read files, inodes and blocks straight out of an ext2, ext3 or ext4 image with debugfs, no mounting required. This guide covers finding files by path or inode, reading their metadata, and copying 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.
• Privileges: on a real block device, reading it may require elevated privileges.
• Never: use a mounted filesystem as a write target for repair work.

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

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.

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.
• Pick the output carefully. Choose a directory with enough free space, and do not point it at an important existing file.
• Metadata is optional. 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

4. Trace blocks for lower-level problems

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.

5. Stay away from commands that change 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.

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.

Two more options change how damaged metadata is handled, and neither repairs it:

• -n disables metadata checksum verification. Reserve it for a specific diagnostic reason.
• -c opens in catastrophic mode, skips initially reading inode and group bitmaps, and forces read-only access.

Common traps

• "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.