Journaling for ext2fs, release 0.0.7a

Released 5 June, 2001
Stephen Tweedie <sct@redhat.com>

Changes in this release
-----------------------

****************************************************************
The major change in this release is a missing byte-endian conversion
in the recovery code. This problem affects both the ext3 kernel
recovery and the recovery code in e2fsck. Please upgrade to
e2fsprogs-1.21-WIP-0601.tar.gz or later. You can find this on
ftp://download.sourceforge.net/pub/sourceforge/e2fsprogs
****************************************************************

The other significant change is a fix when running shared mmaped files
on ext3 with more than one ext3 filesystem active: it was possible for
ext3 to get confused about which filesystem was active if the VM tried
to swap out a page on one filesystem while processing a filesystem
update on the other filesystem.

The other changes include:

Pin the buffer heads backing an inode to a transaction when the
transaction starts, to prevent the inode being flushed to disk before
transaction commit.

Add a debugging check to trap any attempts to run a nested transaction
inside a transaction on a different filesystem.

Fix an assertion failure that could occur after allocating an
indirect block but failing to allocate a block beneath it due to disk
full.

Fix a bug which meant that writes larger than 4k were never being
coalesced into a single transaction.

Rename the confusingly-named "tid_ge" transaction-greater-than
function to "tid_gt"

Update the README to describe the new ext3 features of current
e2fsprogs.

{ For older changes, see the file CHANGES. }


Introduction
------------

What is journaling?

* It means you don't have to fsck after a crash. Basically.

What works?

* Journaling to a journal file on the journaled filesystem

* Automatic recover when the filesystem is remounted

* All VFS operations (including quota) should be journaled

* Add data updates are also journaled


What is left to be done?

* Quota support for non-data-journaled filesystems.

* Journaling to an off-filesystem device, eg. NVRam

* Decent documentation!

* A few internal cleanups: migrating the extra buffer_head fields to
a separate jfs_buffer_info field in particular.

How to apply
------------

This README should have come with two diffs for kernel version
linux-2.2.19:

-rw-rw-r-- 1 sct sct 444464 Jun 5 21:04 linux-2.2.19.ext3.diff
-rw-rw-r-- 1 sct sct 218804 Jun 5 18:52 linux-2.2.19.kdb.diff

The first diff is copy of SGI's kdb kernel debugger patches. Apply this
first if you want kdb. The second patch is the ext3 filesystem. If you
apply this without the kdb diff, you will get a couple of rejects (the
ext3 diff includes a kdb module for interrogating jfs data structures)
--- ignore those.

If you can't apply kernel patches, stop reading this now. Right now!

Now, configure the kernel, saying YES to "Enable Second extended fs
development code" (I *assume* you want it!), and build it.

The release also includes packaged versions of e2fsprogs which include
mke2fs and e2fsck support for ext3 filesystems.


What next?
----------

Now, you want to make a journaled filesystem (recommended) or journal
an existing one. Great. Making a new ext3 filesystem is easy: you
just use the mke2fs from a recent e2fsprogs, and use the "-j" option
when running mke2fs. All e2fsprogs from 1.20 can do this (you should
be running at least 1.21-WIP-0601 to make sure you don't run into a
recovery bug in older versions of the ext3 code.) The "-j" tells
mke2fs to create an ext3 filesystem with a hidden journal (adding a
"-Jsize=<n>" option will set it to be of size <n> MB: 10MB is a good
size to choose.)

To upgrade an existing ext2 filesystem to ext3, just use "tune2fs -j
/dev/<device>". This will work for mounted and unmounted filesystems,
and will even work on the current root filesystem. The only thing
that changes if the filesystem is already mounted is that tune2fs will
create the journal in a file ".journal" in the top-level directory of
the filesystem, rather than using a hidden system inode for it.

Be aware that the jfs patch does _not_ change the ext2 code. Rather, it
makes a copy of ext2 called ext3, and all the fancy footwork takes place
in that. You don't have to run ext3 on all your valuable filesystems if
you don't want to.

Bingo. That's it. Enjoy!


How to fsck
-----------

As long as you are using a recent e2fsprogs, e2fsck should work just as
expected on both ext2 and ext3 filesystems. The new e2fsck fully
understands the ext3 journal.

The recommended e2fsck is from sourceforge: look for
e2fsprogs-1.20.WIP.sct-20010216 in the same place where you got the ext3
kernel patches.

If you use an older version of e2fsck from e2fsprogs-1.17 or later, then
you can now run e2fsck quite happily on the filesystem, but *only as
long as the filesystem was unmounted cleanly*. If it wasn't, then
you'll need to get the kernel code to recover the journal from the disk
by mounting the filesystem (even a readonly mount will cause a journal
recovery to happen) and umounting it again (or, for the root filesystem,
remounting it readonly with "mount -o remount,ro /").



How to move back from ext3 to ext2
----------------------------------

It's quite easy. If you unmount an ext3 filesystem cleanly, then you
can remount it as ext2 without any other commands. If you crash and are
left with an unclean ext3 filesystem, on the other hand, the filesystem
will prevent you from mounting it as ext2: it is not safe to mount it
until you have recovered the journal, and the only way to do that for
now is to mount it as ext3.

However, if for any reason you do have an ext3 filesystem which you want
to convert permanently back to ext2, whether it was cleanly unmounted or
not, you can use "debugfs" from e2fsprogs-1.17 or later to do it.
First, run debugfs and open the filesystem (the -w flag means open for
write, and the -f flag forces it to open the filesystem even if there
are unknown journal flags set):

[root@sarek /root]# debugfs
debugfs 1.18, 11-Nov-1999 for EXT2 FS 0.5b, 95/08/09
debugfs: open -f -w /dev/sdb1

Now, use "features" to see which feature bits are set on the filesystem:

debugfs: features
Filesystem features: has_journal filetype sparse_super

We want to clear the journal bits, then we can quit:

debugfs: features -has_journal -needs_recovery
Filesystem features: filetype sparse_super
debugfs: quit
[root@sarek /root]# debugfs

That's it!




Enjoy.
--Stephen.