aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDave Kleikamp <shaggy@austin.ibm.com>2006-10-11 04:21:25 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-10-11 14:14:19 -0400
commitfc513a333b45f8913d40c8241a0cb61be79e1c60 (patch)
tree1abd23dd907da0ca29ff0511aeda238efbaa8662
parent63f5793351d821749979e36889f9c089c6028c83 (diff)
[PATCH] Documentation/filesystems/ext4.txt
This file, ext4.txt, was put together with information from Andrew Morton, Andreas Dilger, Suparna Bhattacharya, and Ted Ts'o. I copied the mount options, with the exception of "extents", from ext3.txt, so if anyone is aware of anything out-of-date, please let me know. Signed-off-by: Dave Kleikamp <shaggy@austin.ibm.com> Cc: Theodore Ts'o <tytso@mit.edu> Cc: Suparna Bhattacharya <suparna@in.ibm.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
-rw-r--r--Documentation/filesystems/00-INDEX2
-rw-r--r--Documentation/filesystems/ext4.txt236
2 files changed, 238 insertions, 0 deletions
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
index 3c384c0cf86e..4dc28cc93503 100644
--- a/Documentation/filesystems/00-INDEX
+++ b/Documentation/filesystems/00-INDEX
@@ -34,6 +34,8 @@ ext2.txt
34 - info, mount options and specifications for the Ext2 filesystem. 34 - info, mount options and specifications for the Ext2 filesystem.
35ext3.txt 35ext3.txt
36 - info, mount options and specifications for the Ext3 filesystem. 36 - info, mount options and specifications for the Ext3 filesystem.
37ext4.txt
38 - info, mount options and specifications for the Ext4 filesystem.
37files.txt 39files.txt
38 - info on file management in the Linux kernel. 40 - info on file management in the Linux kernel.
39fuse.txt 41fuse.txt
diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt
new file mode 100644
index 000000000000..6a4adcae9f9a
--- /dev/null
+++ b/Documentation/filesystems/ext4.txt
@@ -0,0 +1,236 @@
1
2Ext4 Filesystem
3===============
4
5This is a development version of the ext4 filesystem, an advanced level
6of the ext3 filesystem which incorporates scalability and reliability
7enhancements for supporting large filesystems (64 bit) in keeping with
8increasing disk capacities and state-of-the-art feature requirements.
9
10Mailing list: linux-ext4@vger.kernel.org
11
12
131. Quick usage instructions:
14===========================
15
16 - Grab updated e2fsprogs from
17 ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs-interim/
18 This is a patchset on top of e2fsprogs-1.39, which can be found at
19 ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/
20
21 - It's still mke2fs -j /dev/hda1
22
23 - mount /dev/hda1 /wherever -t ext4dev
24
25 - To enable extents,
26
27 mount /dev/hda1 /wherever -t ext4dev -o extents
28
29 - The filesystem is compatible with the ext3 driver until you add a file
30 which has extents (ie: `mount -o extents', then create a file).
31
32 NOTE: The "extents" mount flag is temporary. It will soon go away and
33 extents will be enabled by the "-o extents" flag to mke2fs or tune2fs
34
35 - When comparing performance with other filesystems, remember that
36 ext3/4 by default offers higher data integrity guarantees than most. So
37 when comparing with a metadata-only journalling filesystem, use `mount -o
38 data=writeback'. And you might as well use `mount -o nobh' too along
39 with it. Making the journal larger than the mke2fs default often helps
40 performance with metadata-intensive workloads.
41
422. Features
43===========
44
452.1 Currently available
46
47* ability to use filesystems > 16TB
48* extent format reduces metadata overhead (RAM, IO for access, transactions)
49* extent format more robust in face of on-disk corruption due to magics,
50* internal redunancy in tree
51
522.1 Previously available, soon to be enabled by default by "mkefs.ext4":
53
54* dir_index and resize inode will be on by default
55* large inodes will be used by default for fast EAs, nsec timestamps, etc
56
572.2 Candidate features for future inclusion
58
59There are several under discussion, whether they all make it in is
60partly a function of how much time everyone has to work on them:
61
62* improved file allocation (multi-block alloc, delayed alloc; basically done)
63* fix 32000 subdirectory limit (patch exists, needs some e2fsck work)
64* nsec timestamps for mtime, atime, ctime, create time (patch exists,
65 needs some e2fsck work)
66* inode version field on disk (NFSv4, Lustre; prototype exists)
67* reduced mke2fs/e2fsck time via uninitialized groups (prototype exists)
68* journal checksumming for robustness, performance (prototype exists)
69* persistent file preallocation (e.g for streaming media, databases)
70
71Features like metadata checksumming have been discussed and planned for
72a bit but no patches exist yet so I'm not sure they're in the near-term
73roadmap.
74
75The big performance win will come with mballoc and delalloc. CFS has
76been using mballoc for a few years already with Lustre, and IBM + Bull
77did a lot of benchmarking on it. The reason it isn't in the first set of
78patches is partly a manageability issue, and partly because it doesn't
79directly affect the on-disk format (outside of much better allocation)
80so it isn't critical to get into the first round of changes. I believe
81Alex is working on a new set of patches right now.
82
833. Options
84==========
85
86When mounting an ext4 filesystem, the following option are accepted:
87(*) == default
88
89extents ext4 will use extents to address file data. The
90 file system will no longer be mountable by ext3.
91
92journal=update Update the ext4 file system's journal to the current
93 format.
94
95journal=inum When a journal already exists, this option is ignored.
96 Otherwise, it specifies the number of the inode which
97 will represent the ext4 file system's journal file.
98
99journal_dev=devnum When the external journal device's major/minor numbers
100 have changed, this option allows the user to specify
101 the new journal location. The journal device is
102 identified through its new major/minor numbers encoded
103 in devnum.
104
105noload Don't load the journal on mounting.
106
107data=journal All data are committed into the journal prior to being
108 written into the main file system.
109
110data=ordered (*) All data are forced directly out to the main file
111 system prior to its metadata being committed to the
112 journal.
113
114data=writeback Data ordering is not preserved, data may be written
115 into the main file system after its metadata has been
116 committed to the journal.
117
118commit=nrsec (*) Ext4 can be told to sync all its data and metadata
119 every 'nrsec' seconds. The default value is 5 seconds.
120 This means that if you lose your power, you will lose
121 as much as the latest 5 seconds of work (your
122 filesystem will not be damaged though, thanks to the
123 journaling). This default value (or any low value)
124 will hurt performance, but it's good for data-safety.
125 Setting it to 0 will have the same effect as leaving
126 it at the default (5 seconds).
127 Setting it to very large values will improve
128 performance.
129
130barrier=1 This enables/disables barriers. barrier=0 disables
131 it, barrier=1 enables it.
132
133orlov (*) This enables the new Orlov block allocator. It is
134 enabled by default.
135
136oldalloc This disables the Orlov block allocator and enables
137 the old block allocator. Orlov should have better
138 performance - we'd like to get some feedback if it's
139 the contrary for you.
140
141user_xattr Enables Extended User Attributes. Additionally, you
142 need to have extended attribute support enabled in the
143 kernel configuration (CONFIG_EXT4_FS_XATTR). See the
144 attr(5) manual page and http://acl.bestbits.at/ to
145 learn more about extended attributes.
146
147nouser_xattr Disables Extended User Attributes.
148
149acl Enables POSIX Access Control Lists support.
150 Additionally, you need to have ACL support enabled in
151 the kernel configuration (CONFIG_EXT4_FS_POSIX_ACL).
152 See the acl(5) manual page and http://acl.bestbits.at/
153 for more information.
154
155noacl This option disables POSIX Access Control List
156 support.
157
158reservation
159
160noreservation
161
162bsddf (*) Make 'df' act like BSD.
163minixdf Make 'df' act like Minix.
164
165check=none Don't do extra checking of bitmaps on mount.
166nocheck
167
168debug Extra debugging information is sent to syslog.
169
170errors=remount-ro(*) Remount the filesystem read-only on an error.
171errors=continue Keep going on a filesystem error.
172errors=panic Panic and halt the machine if an error occurs.
173
174grpid Give objects the same group ID as their creator.
175bsdgroups
176
177nogrpid (*) New objects have the group ID of their creator.
178sysvgroups
179
180resgid=n The group ID which may use the reserved blocks.
181
182resuid=n The user ID which may use the reserved blocks.
183
184sb=n Use alternate superblock at this location.
185
186quota
187noquota
188grpquota
189usrquota
190
191bh (*) ext4 associates buffer heads to data pages to
192nobh (a) cache disk block mapping information
193 (b) link pages into transaction to provide
194 ordering guarantees.
195 "bh" option forces use of buffer heads.
196 "nobh" option tries to avoid associating buffer
197 heads (supported only for "writeback" mode).
198
199
200Data Mode
201---------
202There are 3 different data modes:
203
204* writeback mode
205In data=writeback mode, ext4 does not journal data at all. This mode provides
206a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
207mode - metadata journaling. A crash+recovery can cause incorrect data to
208appear in files which were written shortly before the crash. This mode will
209typically provide the best ext4 performance.
210
211* ordered mode
212In data=ordered mode, ext4 only officially journals metadata, but it logically
213groups metadata and data blocks into a single unit called a transaction. When
214it's time to write the new metadata out to disk, the associated data blocks
215are written first. In general, this mode performs slightly slower than
216writeback but significantly faster than journal mode.
217
218* journal mode
219data=journal mode provides full data and metadata journaling. All new data is
220written to the journal first, and then to its final location.
221In the event of a crash, the journal can be replayed, bringing both data and
222metadata into a consistent state. This mode is the slowest except when data
223needs to be read from and written to disk at the same time where it
224outperforms all others modes.
225
226References
227==========
228
229kernel source: <file:fs/ext4/>
230 <file:fs/jbd2/>
231
232programs: http://e2fsprogs.sourceforge.net/
233 http://ext2resize.sourceforge.net
234
235useful links: http://fedoraproject.org/wiki/ext3-devel
236 http://www.bullopensource.org/ext4/