Safely Replay an e2undo Log on an ext4 File System

You will identify the target, perform a no-write rehearsal, and then replay an e2fsprogs undo log against an ext2, ext3 or ext4 file system when you have verified that the log and target belong together. The installed command is e2undo from e2fsprogs 1.47.0-2.4~exp1ubuntu4.1. Allow 15 to 30 minutes for the checks, plus whatever time the replay needs.

This is an administrative recovery operation. e2undo writes file system blocks directly. A wrong device, an unrelated log or an incorrect offset can make the situation worse. Work from a console or maintenance shell, stop anything that may write the target, and have a current image or other recovery path before you begin. Use elevated privileges only for the commands that need access to the device or mount state.

1. Check the installed command

First confirm which binary and package version you are using. These are read-only checks and normally need no elevated privileges:

$ command -v e2undo
/usr/sbin/e2undo
$ dpkg-query -W -f='${Package} ${Version}\n' e2fsprogs
e2fsprogs 1.47.0-2.4~exp1ubuntu4.1
$ e2undo -h
Usage: e2undo [-f] [-h] [-n] [-o offset] [-v] [-z undo_file] <transaction file> <filesystem>

The two required operands are the undo log, also called the transaction file in the usage message, and the file system device. A device can be a block device or a file containing a file system. The command does not discover the right target from the log name.

2. Stop writes and record the target

Do not replay a log against a mounted, actively changing file system. Identify the target with a read-only command, then stop services or unmount it according to your normal maintenance procedure. Replace the example values with real paths; do not paste them unchanged:

$ LOG='/path/to/verified.undo'
$ DEVICE='/dev/mapper/example-volume'
$ ls -l -- "$LOG" "$DEVICE"
$ findmnt --source "$DEVICE"

findmnt shows whether the device is mounted and where. An empty result does not prove that no process has the device open, so check your service ownership and maintenance plan as well. If the target is a file-system image, keep that image closed in other tools while the replay runs.

Do not use -f to get past an identity mismatch at this stage. By default, e2undo checks the file system superblock and refuses when the undo log does not match the target. That refusal is a safety mechanism, not a nuisance to suppress.

3. Rehearse without writing blocks

Run the exact operation with -n first. The option is a dry run: e2undo does not write the blocks back to the file system:

# e2undo -n "$LOG" "$DEVICE"

The command may produce little or no output. The useful result is its exit status:

# status=$?
# printf 'dry-run exit status: %s\n' "$status"
dry-run exit status: 0

A non-zero status means that you should stop and read the diagnostic. Common boundaries are an unreadable log or device, a malformed transaction file, and a superblock mismatch. Do not respond to a mismatch by adding -f unless you have independently proved that the target is the matching file system and you accept the risk of disabling the check.

4. Choose the replay command

The simplest replay uses the same two operands without -n:

# e2undo "$LOG" "$DEVICE"
# printf 'replay exit status: %s\n' "$?"
replay exit status: 0

This is the point at which file system blocks change. It is not reversible merely because the command has finished. Keep the original log and your recovery copy until the file system has been checked and the failed e2fsprogs operation has been safely repeated or abandoned.

Use -v when you need progress information about the block currently being replayed:

# e2undo -v "$LOG" "$DEVICE"

Do not run a second replay simply to obtain more detail after a successful first replay. If you need a more observable run, decide that before the write operation and repeat only from a known-good recovery copy.

5. Protect the blocks being overwritten

The -z option tells e2undo to write the old contents of each overwritten block to a separate undo file before overwriting it:

# BACKUP='/path/to/e2undo-before-replay.undo'
# e2undo -z "$BACKUP" "$LOG" "$DEVICE"

Choose a destination with enough space and keep it off the file system being repaired where practical. If you pass an empty string to -z, e2undo uses a name based on the device, e2undo-DEVICE.e2undo, in the directory selected by the E2FSPROGS_UNDO_DIR environment variable. Make that location explicit when you need predictable recovery handling:

# export E2FSPROGS_UNDO_DIR='/path/to/undo-directory'
# e2undo -z '' "$LOG" "$DEVICE"

The manpage warns that this protective undo file cannot recover from a power failure or system crash. It is not a substitute for a complete image, a stable maintenance environment or tested backups.

6. Handle offsets and forced checks carefully

If the file system begins at a byte offset inside a larger device or file, supply that offset with -o:

# OFFSET_BYTES='1048576'
# e2undo -n -o "$OFFSET_BYTES" "$LOG" "$DEVICE"

The value is in bytes, not sectors or blocks. Complete a successful dry run with the same offset before allowing writes. If the file system is at the beginning of the target, omit -o; do not add a guessed zero offset just to make the command look explicit.

-f disables the superblock match check. Treat it as a last-resort exception requiring a written reason, an independently verified target and a recovery copy. It is not a repair option and does not fix a wrong log.

7. Verify and recover

After a replay, keep the target out of normal service until the file system has been checked with the appropriate e2fsprogs tools and the check reports a result you understand. The exact checker invocation depends on the file system and your distribution's recovery procedure. Re-mount or restart services only after that check and your application-level verification succeed.

If replay fails, do not keep changing flags or repeatedly replaying the same target. Preserve the diagnostic, the original log and any -z undo file, then return to the last known-good image or involve the administrator responsible for the storage system. e2undo has no general undo command for a replay; the recovery route is a separate, known-good copy or a deliberately retained undo file used against the correct target.