ext4magic(8)

📦
version 0.3.2 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

okay bestie, sit down, we're doing ext4magic(8) — yeah it's section 8, the admin tools corner of the manual, and it's a lot, so hydrate first 💖

✨ NAME ✨

ext4magic — recover deleted files on ext3/4 filesystems 🦋

✨ SYNOPSIS ✨

ext4magic {-M|-m} [-j <journal_file>] [-d <target_dir>] <filesystem>

ext4magic [-S|-J|-H|-V|-T] [-x] [-j <journal_file>] [-B n|-I n|-f
<file_name>|-i <input_list>] [-t n|[[-a n][-b n]]] [-d <target_dir>]
[-R|-r|-L|-l] [-Q] <filesystem>

🌸 DESCRIPTION 🌸

So here's the tea: when you delete a file on an ext3/4 filesystem, it does not just come back with a sad little undo button. The block references in the Inode get zeroed out, and boom — that's what makes a normal reversal literally impossible. 💀

But! Other programs have shown that it's often possible to pull enough info straight out of the filesystem Journal to recover a whole bunch of data files. That's the whole vibe of ext4magic: it extracts information from the Journal and can restore files in entire directory trees — if the Journal actually has enough info in it to work with.

When it works, it goes hard. This tool can recover the most file types, it can recover large and sparse files, and the recovered files come back with the original filename, the original owner and group, the original file mode bits, and even the old atime/mtime stamp. 👑

Real talk though: the filesystem Journal has a very different purpose, so you will not be able to recover any file at any time. So many factors decide which data ends up in the Journal and how long it stays there. For the full lore on the filesystem Journal, go read the ext4magic documentation. 📚

💅 OPTIONS 💅

🎀 Magic Options 🎀

These are the multi-stage recover options — built especially for restoring files after a recursive deletion of parts of the filesystem, or the whole thing. (Third step is currently available for ext3 in versions 0.2.x; the ext4 version is included in version 0.3.x.)

Umount the file system directly after an accidental destroy, and use these options on the umounted file system — or on a copy of it. No cap. 🙈

The program automatically works out the correct time options if the deletion only happened a short time ago (< 5 min). For very large deletions, you must use the "after time".

In the first and second step, files get restored from copies of inodes. The third step tries to restore the remaining files without inode copies. Heads up: this can take a long time. 🐢

  • -M — Try to recover all files. Use this one if the entire Filesystem was deleted.
  • -m — Try to recover only all deleted files. Use this one with a partially deleted Filesystem.

🎀 Information Options 🎀

These generate generic status info from the filesystem and the Journal.

  • -S — Print the filesystem superblock. The option -x allows the additional display of the content of the group descriptor table.
  • -J — Print the content of the Journal superblock. This option can also be used to force loading the Journal. It has a flow control effect in ext4magic with some other options.
  • -H — Output a histogram of time stamps from all filesystem Inodes. This lets you determine the exact time of changes in the filesystem. In connection with a directory name or a directory Inode, only the time stamps of that directory tree get displayed. No changes are evaluated here — just one per Inode: either the last change or the deletion time per Inode arrives at the display. If present (ext4), it also creates a histogram of create time stamps. The optional option -x additionally allows a better resolution of the time intervals.
  • -V — Print the version of ext4magic and libext2fs.
  • -T — Display the entire transaction list of all copies of data blocks in the Journal. In conjunction with -B, -I and -f, only display the corresponding data blocks for this data. The optional option -x allows an additional transmission time of the transactions — but only if the block is an Inode block. The print is in the same order as the data in the journal, so you can draw conclusions from the data received in the Journal. ⚠️ After the import of backups or after a change of timestamps of files, the additional transmission time will not always display the real transmission time. If you see absolutely incorrect time entries here, then check whether you're using a journal of a read-write open file system.
  • -x — Controls, optionally, the output format and the information content of certain commands. Affects the following options: -S, -H, -T, -B, -I, -f, -L, -l. Detailed description — see there.

🎀 Selection Options 🎀

These options specify the exact files, directories, and data blocks. On one hand they produce specific information, and on the other hand they're used to address the data for the Action Options. ext4magic will accept only one of these options per command. 🚫

  • -B n — n is the data block number of a filesystem datablock. Without further options it prints a "one-byte" hex+ASCII dump from the data block on the filesystem, like the hexdump -C command. The optional option -x produces a "four byte" hex+ASCII output.

With the option -t n it prints a copy of the filesystem data block with this transaction number from the Journal.

# ext4magic /dir/filesystem.iso -B 97 -t 22

That prints a hexdump of the copy from filesystem block number 97, which has been written to the Journal with the transaction number 22. All copies of a particular data block in the Journal and the associated transaction numbers — you can find those with the optional option -T.

# ext4magic /dir/filesystem.iso -B 97  -T

That will print a list with all copies of filesystem block number 97 with the transaction numbers. If this data block is an Inode block, it prints out the exact time for the transaction with the optional option -x.

  • -I n — n is the Inode number. Without any other option, the output is the content of the real filesystem Inode. With an optional -x, additional output of a list of all data blocks addressed by this Inode. If the Inode is a directory Inode, the content of the directory entries is also printed.

Together with one of the following options, -T, -J, the output is not the content from the real filesystem Inode — the content of all different Inode copies found in the Journal gets printed instead.

With the option -t n, only the content of the Inode from transaction "n" is printed.

The option -I n can also be used in conjunction with the options -L, -l, -r or -R (show there).

  • -f <filename> — The function is the same as -I n, only here the <filename> is given instead of the Inode number. ext4magic searches the filesystem to find the Inode number. The filename can be a directory or a filename, and it must be specified here from the root directory of this filesystem — not from the root directory of the LINUX system. 🫶

An example: the mount point for this filesystem is /home and the filename for Linux is /home/usr1/Document, so you can now use

# ext4magic /dev/sda3 -f usr1/Document

The root directory of the filesystem you can use

-f /

or

-f ""

For ext4magic this is the same.

You should specify no leading / for all other filenames. And for directory names you should specify them without a final /. ✨

🧚 Expert Options 🧚

(new in 0.2.1) The optional Expert-Mode must be enabled with the option --enable-expert-mode by configure. This makes it possible to open and recover from corrupted file systems. In the current version it's possible to address backup superblocks and attempt to recover the Journal address from the data of the superblock, and recover all undamaged files after the filesystem was partially damaged or overwritten. 🔥

  • -s blocksize -n blocknumber — With these options you can select the backup superblock. blocksize can be 1024, 2048 or 4096. blocknumber is the block number of the backup superblock; this depends on the block size. Use the same values as with fsck or debugfs, or use the output of mkfs -n .. to determine the correct value.
Use the options necessarily in the order -s ... -n ...
  • -c — This will attempt to find the journal using the data of the superblock. Can help if the first inode blocks of the file system are damaged.
  • -D — Trying a restore of all files from a badly damaged file system. The combination of all these Expert Options attempts a file system restore if the superblock is broken and the beginning of the file system is corrupted or overwritten. This can only work if e2fsck has not yet changed the faulty file system.

Example: the first few megabytes of the file system are overwritten. The following tries a copy of all undamaged files of the filesystem. Target directory is /tmp/recoverdir

# ext4magic /dev/sda1 -s 4096 -n 32768 -c -D -d /tmp/recoverdir
  • -Q — This is an optional high quality option for recover, and it only impacts with -r and -R. Without this option, any valid file name is restored from the directories, and you can set the "before" time stamp to a time in which all files are deleted — so you will find the maximum possible number of files. It need not necessarily find old directory data blocks in the Journal. However, there are some files found too many. In this mode, re-used file names and re-used Inodes can not be noticed. As a result, some files will be created with the extension #, or some files created with wrong content. You have to check the files and find bad files and delete them yourself. 😭

With option -Q, ext4magic works more accurately, and can avoid such false and duplicate files. This requires old data blocks of the directories in the Journal. You will not find old blocks of all directories in the Journal — only directories in which files have been previously created or deleted, but not directories in which no change has been made for a long time. You should set the time stamp "before" immediately before the destruction time of the files. If not enough directory data is available, it may be that ext4magic can't find deleted files or entire directory content. This option should be used very carefully and will achieve good results only in a few directories. ⚠️

🌈 Time Options 🌈

With these options you specify a time window in which the program searches for matching time stamps in the Journal data. ext4magic requires two times for most of its internal functions: a time "after" and a time "before". ⏳

Okay so, an inode only gets accepted if it’s not deleted and its time stamp is less than before. If the delete time is less than after, that inode is also not used. ext4magic is still trying to find, for a valid directory inode, also a time-matching directory data. For a recover action, set before to a value at which the data deleted, and after to a value at which the data available. Inodes and directory data with other timestamps will be skipped and not used, periodt. 💅

Default, without any time option, ext4magic will search with now for the internal time before, and now -24 hour for the internal time after. If you try to recover without any time option, so you search only over the last 24 hours. If you wait a couple of days before you try to recover deleted data, you must always use time options, or you find nothing 😭. fr fr.

  • -a n — with this option you can set the after time.
  • -b n — with this option you can set the before time.

n is the number of seconds since 1970-01-01 00:00:00 UTC. This time information can you find in many prints of ext4magic, and you can it produce on the console with the command date and also insert directly in the ext4magic command line. ✨

-a $(date -d "-3day" +%s) -b $(date -d "-2day" +%s)

this example set after=now-36h and before=now-24h. 🕰️

  • -t n — is an indirect time option. you can use it with the options -B ; -I ; -f The value n is the transaction number. With this option you can print, list, or recover the data from this transaction number. you can find the transaction numbers with the option -T or in the print of the Inode content.

File-, IN- and OUT-Options 🗂️

With these options group, you select the filesystem, and other optional file input and output for control of ext4magic.

  • <filesystem> — selects the filesystem and must always be set. <filesystem> can be a blockdevice with ext3/4 filesystem, it can also be a uncompressed file image of such a partition.
  • -j <journal_file> — optional you can select a external copy of the Journal file. Without this option, automatically the internal Journal or, if configured, the external Journal on a block device will used.
  • -d <target_dir> — select the output directory. There, the recovered files were written. If it does not exist, it is created. By default, created files are written to the subdirectory RECOVERDIR in the workpath of the actual shell. This output directory can not be on the same filesystem to be tested filesystem, and should have sufficient space to write the recovered files. The filesystem on this directory should be also ext3/4, otherwise, not LINUX like filesystems generate some errors while writing the file properties. Either you must first changed with the shell in such a suitable filesystem, or you must specify the -d with a target to such a directory. 🎀
  • -i <input_list> — input_list is a input file. Must contain a list with double-quoted filenames. The files from the list will be restored with option -r or -R.

Blank lines, not cleanly double quoted filenames and all areas before and after " will be ignored. Such a double-quoted list of file names can create with options -l -x or -L -x by ext4magic and edited by script or by hand.

Action Options 🎬

This option group includes list and recover options. All functions together, they work recursiv controlled by the time options through directory trees. The starting point for search is determined by a directory name or a directory Inode number. Default is root of this Filesystem. Matching the time options, the filesystem data, inclusive directory data, taken from the Journal. If good data from the file system sections available in Journal, it is possible to see or recover the state of the filesystem at different times. 👑

  • -L — Prints the list of all filenames and Inode number of the selected directory tree. Included here also are deleted files and deleted directory trees. With the additional option -x the file names are printed double-quoted. You can use it for a "Input list" with option -i.
  • -l — Prints a list of all filenames which have not allocated data blocks. At the beginning of the line are the percentage of unallocated data blocks. After deletion you find here all the file names you can recover with the Journal data. If you use a very old value for the before time, it is possible there are files whose data blocks reused and these files in the interim also been deleted. Also included in the list all files without data blocks, symbolic links, empty and other special files.

Likewise double-quoted file names with optional -x.

  • -r — applied to directories, all files without conflicts with the occupied blocks will recovered. This are all you can sea with the option -l and be 100% unallocated. This options only recover deleted files and files without data blocks, in example: symbolic links or empty files.

The recovered files written to RECOVERDIR/ This can also set to an alternate <target_dir> with the option -d.

All files become the old filename and if possible, also the old file properties. A subdirectory tree can set with "-f dirname" oder "-I inodenumber" If use with a given Inode number, the directory name is set to <inodenumber>.

The Time options affect the search. If a file name already exists, or you recover again, it not overwrite files, and a new filename by added a final "#" will created. The maximum ist the extension " ##### " for a filename.

single files also can recovered, possible search with time-stamps or transaction number.

(new 0.2.1): Starts this function from the root directory the first stage of the magic functions will follow.

This starts "lost directory search" and "lost file search" and recovers all the deleted inode that can not be assigned to a file name. These files you can find in the directories MAGIC-1 and MAGIC-2. 🦋

  • -R — recovers directory tree, is the same as -r.

But two very important differences: Recover of all matched Inodes, even if the blocks allocated, and recover if possible the old directory properties. Also empty directories will be restored. This recovers all deleted and all undeleted files, and it's possible to recover older file versions or directory versions.

In completely deleted directories the behavior " -R " and " -r " is identical. The difference is there only the complete recover of all directories with option " -R ". You can also restore individual files with time options or a transaction number.

For all recover cases ACL, SEL and other extended attribute can not recovered in the current version. 😭

The output starts at line with a string "--------" before the recovered file name. This is a sign of successful recover. Are not enough permissions to write the recovered files, then you will see there some "x" in the string. ✅

At the end of the process, possibly an issue comes from the hardlink database. A positive number before a file name means : not found all hardlinks to this file. A negative number means : it created too many hardlinks to this file (possible are, reused filenames or reused Inodes, and so, too many or wrong old filenames for this hardlink. But also possible, all files for this hardlink are correct, the time options was not set correct and because of that, the selected inode for the recover was not up to date. You should check such reports.) 👀

Re-used data blocks can't realize and so it's possible, it ends in some corrupted files. Check in any case, all the recoverd files before you use them. 💖

🎀 EXAMPLES 🎀

So like, printing the content of an Inode?? There are a few little ways to do that, bestie. Pick your fave 💅

# ext4magic /dev/sda3 -f /

# ext4magic /dev/sda3 -I 2

What comes out is the actual filesystem root Inode. First example? You're handing it a pathname. Second example? Inode 2 is also the root directory, so same energy, different door 🚪✨

# ext4magic /tmp/filesystem.iso -f / -T -x

Okay so here we're using the filesystem image "/tmp/filesystem.iso", searching and printing all transactions of the Block that included the root Inode, and printing all differend Inode — plus the blocklist off the data blocks. And if it's a directory?? Then it also prints, for each individual Inode, the content of the directory. Not me being thorough or whatever 😭💖

# ext4magic /tmp/filesystem.iso -j /tmp/journal.backup -I 8195 -t 182

This one uses the filesystem image "/tmp/filesystem.iso" and reads from an external Journal in the file "/tmp/journal.backup", then prints the content of the Inode number 8195 from the journal transaction number 182. Slay, external journal, slay 🦋

# ext4magic /dev/sda3 -f user1/Documents -a $(date -d "-3 day" +%s) -b $(date -d "-2 day" +%s)

Prints a undeleded Inode for the pathname "user1/Documents" from two to three days back. If it's a directory, then also the content of this directory. And — lowkey important — if it cannot find the old directory blocks in the Journal, the directory content will just be the actual one from the filesystem. No cap.

🌸 Examples of simple Recover 🌸

# ext4magic /dev/sda3 -r -f user1/picture/cim01234.jpg -d /tmp

Recovers the file "/home/user1/picture/cim01234.jpg" which has just been deleted. The file system is mounted normally under "/home". Note: the file path is specified from the root directory of the file system and not from the root of the entire Linux system. Whenever possible, umount the file system for the recover, okay?? It's giving safety 💅 The file will be written as "/tmp/user1/picture/cim01234.jpg"

# ext4magic /dev/sda3 -r

Tries to restore all files deleted in the last 24 hours, and writes them to the directory "./RECOVERDIR/". Iconic default behaviour fr fr 🫶

# ext4magic /dev/sda3 -R -a $(date -d "-5day" +%s)

Attempts to recover all files — even if they're already partially overwritten — and recovers all not deleted files too. The erase time is 4 days ago. Big main-character energy, very greedy in the best way 👑

# ext4magic /dev/sda3 -M -d /home/recover

Tries a multi-stage recover of all files after the filesystem is deleted with a "rm -rf *". Writes the files to "/home/recover". (on ext4 : in this version skipped the last step.) — yeah we said what we said 😭

# ext4magic /dev/sda3 -RQ -f user1/Dokuments -a 1274210280 -b 1274211280 -d /mnt/testrecover

Tries to restore the directory tree "user1/Dokuments/". The "-b" timestamp you must set just before deleting files, and the "-a" timestamp prevents found old file versions. This will only work well if you've there created or deleted files bevor the "-b" timestamp. Writes to the directory "/mnt/testrecover/". And if only a few files recovers?? Attempts the same without the option -Q. Adjust and retry, bestie 🎀

# ext4magic /home/filesystem.iso -Lx  -f user1 | grep "jpg" > ./tmpfile

# ext4magic /home/filesystem.iso -i ./tmpfile -r -d /mnt/testrecover

Tries to restore only all deleted files from the directory tree "user1/" that have "jpg" in the filename (last 24 hour), and writes to "/mnt/testrecover" — using a temporary file "./tmpfile" for a list of filenames. Piping into grep and living your truth ✨

💀 BUGS 💀

Direct use of the Journal of a currently read-write open filesystem produce reading of bad blocks. Such bad blocks provide program errors and false results.

So like... do not do this. You shall therefore never use the Journal of such a read-write open file system directly. Periodt. 🙈

Should it be necessary to use a mounted file system, create a copy of the file system journal and used the option -j. That's the move, that's the vibe check 💅

👑 AUTHOR 👑

Roberto Maar

🌈 SEE ALSO 🌈

debugfs (8) , e2fsck (8)

okay that's literally the whole page bestie, go forth and recover your files responsibly 💖 this was ext4magic version 0.3.2 from Oct 2014 — see you in the ext4magic(8) cinematic universe 🦋✨🎀

📦 where this page comes from