Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 1 | |
| 2 | Ext4 Filesystem |
| 3 | =============== |
| 4 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 5 | Ext4 is an an advanced level of the ext3 filesystem which incorporates |
| 6 | scalability and reliability enhancements for supporting large filesystems |
| 7 | (64 bit) in keeping with increasing disk capacities and state-of-the-art |
| 8 | feature requirements. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 9 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 10 | Mailing list: linux-ext4@vger.kernel.org |
| 11 | Web site: http://ext4.wiki.kernel.org |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 12 | |
| 13 | |
| 14 | 1. Quick usage instructions: |
| 15 | =========================== |
| 16 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 17 | Note: More extensive information for getting started with ext4 can be |
| 18 | found at the ext4 wiki site at the URL: |
| 19 | http://ext4.wiki.kernel.org/index.php/Ext4_Howto |
| 20 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 21 | - Compile and install the latest version of e2fsprogs (as of this |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 22 | writing version 1.41.3) from: |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 23 | |
| 24 | http://sourceforge.net/project/showfiles.php?group_id=2406 |
| 25 | |
| 26 | or |
| 27 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 28 | ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/ |
| 29 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 30 | or grab the latest git repository from: |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 31 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 32 | git://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 33 | |
Theodore Ts'o | 4537398 | 2008-07-27 19:59:21 -0400 | [diff] [blame] | 34 | - Note that it is highly important to install the mke2fs.conf file |
| 35 | that comes with the e2fsprogs 1.41.x sources in /etc/mke2fs.conf. If |
| 36 | you have edited the /etc/mke2fs.conf file installed on your system, |
| 37 | you will need to merge your changes with the version from e2fsprogs |
| 38 | 1.41.x. |
| 39 | |
Theodore Ts'o | 03010a3 | 2008-10-10 20:02:48 -0400 | [diff] [blame] | 40 | - Create a new filesystem using the ext4 filesystem type: |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 41 | |
Theodore Ts'o | 03010a3 | 2008-10-10 20:02:48 -0400 | [diff] [blame] | 42 | # mke2fs -t ext4 /dev/hda1 |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 43 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 44 | Or to configure an existing ext3 filesystem to support extents: |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 45 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 46 | # tune2fs -O extents /dev/hda1 |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 47 | |
| 48 | If the filesystem was created with 128 byte inodes, it can be |
| 49 | converted to use 256 byte for greater efficiency via: |
| 50 | |
| 51 | # tune2fs -I 256 /dev/hda1 |
| 52 | |
Theodore Ts'o | 03010a3 | 2008-10-10 20:02:48 -0400 | [diff] [blame] | 53 | (Note: we currently do not have tools to convert an ext4 |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 54 | filesystem back to ext3; so please do not do try this on production |
| 55 | filesystems.) |
| 56 | |
| 57 | - Mounting: |
| 58 | |
Theodore Ts'o | 03010a3 | 2008-10-10 20:02:48 -0400 | [diff] [blame] | 59 | # mount -t ext4 /dev/hda1 /wherever |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 60 | |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 61 | - When comparing performance with other filesystems, it's always |
| 62 | important to try multiple workloads; very often a subtle change in a |
| 63 | workload parameter can completely change the ranking of which |
| 64 | filesystems do well compared to others. When comparing versus ext3, |
| 65 | note that ext4 enables write barriers by default, while ext3 does |
| 66 | not enable write barriers by default. So it is useful to use |
| 67 | explicitly specify whether barriers are enabled or not when via the |
| 68 | '-o barriers=[0|1]' mount option for both ext3 and ext4 filesystems |
| 69 | for a fair comparison. When tuning ext3 for best benchmark numbers, |
| 70 | it is often worthwhile to try changing the data journaling mode; '-o |
| 71 | data=writeback,nobh' can be faster for some workloads. (Note |
| 72 | however that running mounted with data=writeback can potentially |
| 73 | leave stale data exposed in recently written files in case of an |
| 74 | unclean shutdown, which could be a security exposure in some |
| 75 | situations.) Configuring the filesystem with a large journal can |
| 76 | also be helpful for metadata-intensive workloads. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 77 | |
| 78 | 2. Features |
| 79 | =========== |
| 80 | |
| 81 | 2.1 Currently available |
| 82 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 83 | * ability to use filesystems > 16TB (e2fsprogs support not available yet) |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 84 | * extent format reduces metadata overhead (RAM, IO for access, transactions) |
| 85 | * extent format more robust in face of on-disk corruption due to magics, |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 86 | * internal redundancy in tree |
Mingming Cao | 49f1487 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 87 | * improved file allocation (multi-block alloc) |
Theodore Ts'o | 722bde6 | 2009-02-23 00:51:57 -0500 | [diff] [blame] | 88 | * lift 32000 subdirectory limit imposed by i_links_count[1] |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 89 | * nsec timestamps for mtime, atime, ctime, create time |
| 90 | * inode version field on disk (NFSv4, Lustre) |
| 91 | * reduced e2fsck time via uninit_bg feature |
| 92 | * journal checksumming for robustness, performance |
| 93 | * persistent file preallocation (e.g for streaming media, databases) |
| 94 | * ability to pack bitmaps and inode tables into larger virtual groups via the |
| 95 | flex_bg feature |
| 96 | * large file support |
| 97 | * Inode allocation using large virtual block groups via flex_bg |
Mingming Cao | 49f1487 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 98 | * delayed allocation |
| 99 | * large block (up to pagesize) support |
| 100 | * efficent new ordered mode in JBD2 and ext4(avoid using buffer head to force |
| 101 | the ordering) |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 102 | |
Theodore Ts'o | 722bde6 | 2009-02-23 00:51:57 -0500 | [diff] [blame] | 103 | [1] Filesystems with a block size of 1k may see a limit imposed by the |
| 104 | directory hash tree having a maximum depth of two. |
| 105 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 106 | 2.2 Candidate features for future inclusion |
| 107 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 108 | * Online defrag (patches available but not well tested) |
| 109 | * reduced mke2fs time via lazy itable initialization in conjuction with |
| 110 | the uninit_bg feature (capability to do this is available in e2fsprogs |
| 111 | but a kernel thread to do lazy zeroing of unused inode table blocks |
| 112 | after filesystem is first mounted is required for safety) |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 113 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 114 | There are several others under discussion, whether they all make it in is |
| 115 | partly a function of how much time everyone has to work on them. Features like |
| 116 | metadata checksumming have been discussed and planned for a bit but no patches |
| 117 | exist yet so I'm not sure they're in the near-term roadmap. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 118 | |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 119 | The big performance win will come with mballoc, delalloc and flex_bg |
| 120 | grouping of bitmaps and inode tables. Some test results available here: |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 121 | |
Diego Calleja | 22359f5 | 2008-10-17 09:15:14 -0400 | [diff] [blame] | 122 | - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-write-2.6.27-rc1.html |
| 123 | - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-readwrite-2.6.27-rc1.html |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 124 | |
| 125 | 3. Options |
| 126 | ========== |
| 127 | |
| 128 | When mounting an ext4 filesystem, the following option are accepted: |
| 129 | (*) == default |
| 130 | |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 131 | ro Mount filesystem read only. Note that ext4 will |
| 132 | replay the journal (and thus write to the |
| 133 | partition) even when mounted "read only". The |
| 134 | mount options "ro,noload" can be used to prevent |
| 135 | writes to the filesystem. |
| 136 | |
Linus Torvalds | d4da6c9 | 2009-11-02 10:15:27 -0800 | [diff] [blame] | 137 | journal_checksum Enable checksumming of the journal transactions. |
| 138 | This will allow the recovery code in e2fsck and the |
| 139 | kernel to detect corruption in the kernel. It is a |
| 140 | compatible change and will be ignored by older kernels. |
| 141 | |
Girish Shilamkar | 818d276 | 2008-01-28 23:58:27 -0500 | [diff] [blame] | 142 | journal_async_commit Commit block can be written to disk without waiting |
| 143 | for descriptor blocks. If enabled older kernels cannot |
Linus Torvalds | d4da6c9 | 2009-11-02 10:15:27 -0800 | [diff] [blame] | 144 | mount the device. This will enable 'journal_checksum' |
| 145 | internally. |
Girish Shilamkar | 818d276 | 2008-01-28 23:58:27 -0500 | [diff] [blame] | 146 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 147 | journal=update Update the ext4 file system's journal to the current |
| 148 | format. |
| 149 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 150 | journal_dev=devnum When the external journal device's major/minor numbers |
| 151 | have changed, this option allows the user to specify |
| 152 | the new journal location. The journal device is |
| 153 | identified through its new major/minor numbers encoded |
| 154 | in devnum. |
| 155 | |
Eric Sandeen | e3bb52a | 2009-11-19 14:28:50 -0500 | [diff] [blame] | 156 | norecovery Don't load the journal on mounting. Note that |
| 157 | noload if the filesystem was not unmounted cleanly, |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 158 | skipping the journal replay will lead to the |
| 159 | filesystem containing inconsistencies that can |
| 160 | lead to any number of problems. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 161 | |
| 162 | data=journal All data are committed into the journal prior to being |
| 163 | written into the main file system. |
| 164 | |
| 165 | data=ordered (*) All data are forced directly out to the main file |
| 166 | system prior to its metadata being committed to the |
| 167 | journal. |
| 168 | |
| 169 | data=writeback Data ordering is not preserved, data may be written |
| 170 | into the main file system after its metadata has been |
| 171 | committed to the journal. |
| 172 | |
| 173 | commit=nrsec (*) Ext4 can be told to sync all its data and metadata |
| 174 | every 'nrsec' seconds. The default value is 5 seconds. |
| 175 | This means that if you lose your power, you will lose |
| 176 | as much as the latest 5 seconds of work (your |
| 177 | filesystem will not be damaged though, thanks to the |
| 178 | journaling). This default value (or any low value) |
| 179 | will hurt performance, but it's good for data-safety. |
| 180 | Setting it to 0 will have the same effect as leaving |
| 181 | it at the default (5 seconds). |
| 182 | Setting it to very large values will improve |
| 183 | performance. |
| 184 | |
Eric Sandeen | 571640c | 2008-05-26 12:29:46 -0400 | [diff] [blame] | 185 | barrier=<0|1(*)> This enables/disables the use of write barriers in |
Theodore Ts'o | 06705bf | 2009-03-28 10:59:57 -0400 | [diff] [blame] | 186 | barrier(*) the jbd code. barrier=0 disables, barrier=1 enables. |
| 187 | nobarrier This also requires an IO stack which can support |
Eric Sandeen | 571640c | 2008-05-26 12:29:46 -0400 | [diff] [blame] | 188 | barriers, and if jbd gets an error on a barrier |
| 189 | write, it will disable again with a warning. |
| 190 | Write barriers enforce proper on-disk ordering |
| 191 | of journal commits, making volatile disk write caches |
| 192 | safe to use, at some performance penalty. If |
| 193 | your disks are battery-backed in one way or another, |
| 194 | disabling barriers may safely improve performance. |
Theodore Ts'o | 06705bf | 2009-03-28 10:59:57 -0400 | [diff] [blame] | 195 | The mount options "barrier" and "nobarrier" can |
| 196 | also be used to enable or disable barriers, for |
| 197 | consistency with other ext4 mount options. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 198 | |
Fang Wenqi | 6d3b82f | 2009-12-24 17:51:42 -0500 | [diff] [blame] | 199 | inode_readahead_blks=n This tuning parameter controls the maximum |
Theodore Ts'o | 240799c | 2008-10-09 23:53:47 -0400 | [diff] [blame] | 200 | number of inode table blocks that ext4's inode |
| 201 | table readahead algorithm will pre-read into |
| 202 | the buffer cache. The default value is 32 blocks. |
| 203 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 204 | orlov (*) This enables the new Orlov block allocator. It is |
| 205 | enabled by default. |
| 206 | |
| 207 | oldalloc This disables the Orlov block allocator and enables |
| 208 | the old block allocator. Orlov should have better |
| 209 | performance - we'd like to get some feedback if it's |
| 210 | the contrary for you. |
| 211 | |
| 212 | user_xattr Enables Extended User Attributes. Additionally, you |
| 213 | need to have extended attribute support enabled in the |
| 214 | kernel configuration (CONFIG_EXT4_FS_XATTR). See the |
| 215 | attr(5) manual page and http://acl.bestbits.at/ to |
| 216 | learn more about extended attributes. |
| 217 | |
| 218 | nouser_xattr Disables Extended User Attributes. |
| 219 | |
| 220 | acl Enables POSIX Access Control Lists support. |
| 221 | Additionally, you need to have ACL support enabled in |
| 222 | the kernel configuration (CONFIG_EXT4_FS_POSIX_ACL). |
| 223 | See the acl(5) manual page and http://acl.bestbits.at/ |
| 224 | for more information. |
| 225 | |
| 226 | noacl This option disables POSIX Access Control List |
| 227 | support. |
| 228 | |
| 229 | reservation |
| 230 | |
| 231 | noreservation |
| 232 | |
| 233 | bsddf (*) Make 'df' act like BSD. |
| 234 | minixdf Make 'df' act like Minix. |
| 235 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 236 | debug Extra debugging information is sent to syslog. |
| 237 | |
Theodore Ts'o | 8a8a205 | 2009-06-13 10:08:59 -0400 | [diff] [blame] | 238 | abort Simulate the effects of calling ext4_abort() for |
| 239 | debugging purposes. This is normally used while |
| 240 | remounting a filesystem which is already mounted. |
| 241 | |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 242 | errors=remount-ro Remount the filesystem read-only on an error. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 243 | errors=continue Keep going on a filesystem error. |
| 244 | errors=panic Panic and halt the machine if an error occurs. |
Theodore Ts'o | 8e1a485 | 2009-01-06 14:53:06 -0500 | [diff] [blame] | 245 | (These mount options override the errors behavior |
| 246 | specified in the superblock, which can be configured |
| 247 | using tune2fs) |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 248 | |
Hidehiro Kawai | 5bf5683 | 2008-10-10 22:12:43 -0400 | [diff] [blame] | 249 | data_err=ignore(*) Just print an error message if an error occurs |
| 250 | in a file data buffer in ordered mode. |
| 251 | data_err=abort Abort the journal if an error occurs in a file |
| 252 | data buffer in ordered mode. |
| 253 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 254 | grpid Give objects the same group ID as their creator. |
| 255 | bsdgroups |
| 256 | |
| 257 | nogrpid (*) New objects have the group ID of their creator. |
| 258 | sysvgroups |
| 259 | |
| 260 | resgid=n The group ID which may use the reserved blocks. |
| 261 | |
| 262 | resuid=n The user ID which may use the reserved blocks. |
| 263 | |
| 264 | sb=n Use alternate superblock at this location. |
| 265 | |
Jan Kara | 1358870 | 2009-09-18 12:22:29 -0400 | [diff] [blame] | 266 | quota These options are ignored by the filesystem. They |
| 267 | noquota are used only by quota tools to recognize volumes |
| 268 | grpquota where quota should be turned on. See documentation |
| 269 | usrquota in the quota-tools package for more details |
| 270 | (http://sourceforge.net/projects/linuxquota). |
| 271 | |
| 272 | jqfmt=<quota type> These options tell filesystem details about quota |
| 273 | usrjquota=<file> so that quota information can be properly updated |
| 274 | grpjquota=<file> during journal replay. They replace the above |
| 275 | quota options. See documentation in the quota-tools |
| 276 | package for more details |
| 277 | (http://sourceforge.net/projects/linuxquota). |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 278 | |
| 279 | bh (*) ext4 associates buffer heads to data pages to |
| 280 | nobh (a) cache disk block mapping information |
| 281 | (b) link pages into transaction to provide |
| 282 | ordering guarantees. |
| 283 | "bh" option forces use of buffer heads. |
| 284 | "nobh" option tries to avoid associating buffer |
| 285 | heads (supported only for "writeback" mode). |
| 286 | |
Alex Tomas | c9de560 | 2008-01-29 00:19:52 -0500 | [diff] [blame] | 287 | stripe=n Number of filesystem blocks that mballoc will try |
| 288 | to use for allocation size and alignment. For RAID5/6 |
| 289 | systems this should be the number of data |
| 290 | disks * RAID chunk size in file system blocks. |
Jan Kara | 8365388 | 2009-09-29 15:59:34 -0400 | [diff] [blame] | 291 | |
| 292 | delalloc (*) Defer block allocation until just before ext4 |
| 293 | writes out the block(s) in question. This |
| 294 | allows ext4 to better allocation decisions |
| 295 | more efficiently. |
| 296 | nodelalloc Disable delayed allocation. Blocks are allocated |
| 297 | when the data is copied from userspace to the |
| 298 | page cache, either via the write(2) system call |
| 299 | or when an mmap'ed page which was previously |
| 300 | unallocated is written for the first time. |
Theodore Ts'o | 240799c | 2008-10-09 23:53:47 -0400 | [diff] [blame] | 301 | |
Theodore Ts'o | 3077384 | 2009-01-03 20:27:38 -0500 | [diff] [blame] | 302 | max_batch_time=usec Maximum amount of time ext4 should wait for |
| 303 | additional filesystem operations to be batch |
| 304 | together with a synchronous write operation. |
| 305 | Since a synchronous write operation is going to |
| 306 | force a commit and then a wait for the I/O |
| 307 | complete, it doesn't cost much, and can be a |
| 308 | huge throughput win, we wait for a small amount |
| 309 | of time to see if any other transactions can |
| 310 | piggyback on the synchronous write. The |
| 311 | algorithm used is designed to automatically tune |
| 312 | for the speed of the disk, by measuring the |
| 313 | amount of time (on average) that it takes to |
| 314 | finish committing a transaction. Call this time |
| 315 | the "commit time". If the time that the |
Matt LaPlante | 19f5946 | 2009-04-27 15:06:31 +0200 | [diff] [blame] | 316 | transaction has been running is less than the |
Theodore Ts'o | 3077384 | 2009-01-03 20:27:38 -0500 | [diff] [blame] | 317 | commit time, ext4 will try sleeping for the |
| 318 | commit time to see if other operations will join |
| 319 | the transaction. The commit time is capped by |
| 320 | the max_batch_time, which defaults to 15000us |
| 321 | (15ms). This optimization can be turned off |
| 322 | entirely by setting max_batch_time to 0. |
| 323 | |
| 324 | min_batch_time=usec This parameter sets the commit time (as |
| 325 | described above) to be at least min_batch_time. |
| 326 | It defaults to zero microseconds. Increasing |
| 327 | this parameter may improve the throughput of |
| 328 | multi-threaded, synchronous workloads on very |
| 329 | fast disks, at the cost of increasing latency. |
| 330 | |
Theodore Ts'o | b3881f7 | 2009-01-05 22:46:26 -0500 | [diff] [blame] | 331 | journal_ioprio=prio The I/O priority (from 0 to 7, where 0 is the |
| 332 | highest priorty) which should be used for I/O |
| 333 | operations submitted by kjournald2 during a |
| 334 | commit operation. This defaults to 3, which is |
| 335 | a slightly higher priority than the default I/O |
| 336 | priority. |
| 337 | |
Theodore Ts'o | 06705bf | 2009-03-28 10:59:57 -0400 | [diff] [blame] | 338 | auto_da_alloc(*) Many broken applications don't use fsync() when |
| 339 | noauto_da_alloc replacing existing files via patterns such as |
| 340 | fd = open("foo.new")/write(fd,..)/close(fd)/ |
| 341 | rename("foo.new", "foo"), or worse yet, |
| 342 | fd = open("foo", O_TRUNC)/write(fd,..)/close(fd). |
| 343 | If auto_da_alloc is enabled, ext4 will detect |
| 344 | the replace-via-rename and replace-via-truncate |
| 345 | patterns and force that any delayed allocation |
| 346 | blocks are allocated such that at the next |
| 347 | journal commit, in the default data=ordered |
| 348 | mode, the data blocks of the new file are forced |
| 349 | to disk before the rename() operation is |
Matt LaPlante | 19f5946 | 2009-04-27 15:06:31 +0200 | [diff] [blame] | 350 | committed. This provides roughly the same level |
Theodore Ts'o | 06705bf | 2009-03-28 10:59:57 -0400 | [diff] [blame] | 351 | of guarantees as ext3, and avoids the |
| 352 | "zero-length" problem that can happen when a |
| 353 | system crashes before the delayed allocation |
| 354 | blocks are forced to disk. |
| 355 | |
Lukas Czerner | bfff687 | 2010-10-27 21:30:05 -0400 | [diff] [blame] | 356 | noinit_itable Do not initialize any uninitialized inode table |
| 357 | blocks in the background. This feature may be |
| 358 | used by installation CD's so that the install |
| 359 | process can complete as quickly as possible; the |
| 360 | inode table initialization process would then be |
| 361 | deferred until the next time the file system |
| 362 | is unmounted. |
| 363 | |
| 364 | init_itable=n The lazy itable init code will wait n times the |
| 365 | number of milliseconds it took to zero out the |
| 366 | previous block group's inode table. This |
| 367 | minimizes the impact on the systme performance |
| 368 | while file system's inode table is being initialized. |
| 369 | |
Lukas Czerner | 6f9524e | 2011-02-21 20:16:21 -0500 | [diff] [blame] | 370 | discard Controls whether ext4 should issue discard/TRIM |
Eric Sandeen | 5328e63 | 2009-11-19 14:25:42 -0500 | [diff] [blame] | 371 | nodiscard(*) commands to the underlying block device when |
| 372 | blocks are freed. This is useful for SSD devices |
| 373 | and sparse/thinly-provisioned LUNs, but it is off |
| 374 | by default until sufficient testing has been done. |
| 375 | |
Lukas Czerner | 6f9524e | 2011-02-21 20:16:21 -0500 | [diff] [blame] | 376 | nouid32 Disables 32-bit UIDs and GIDs. This is for |
| 377 | interoperability with older kernels which only |
| 378 | store and expect 16-bit values. |
| 379 | |
| 380 | resize Allows to resize filesystem to the end of the last |
| 381 | existing block group, further resize has to be done |
| 382 | with resize2fs either online, or offline. It can be |
| 383 | used only with conjunction with remount. |
| 384 | |
| 385 | block_validity This options allows to enables/disables the in-kernel |
| 386 | noblock_validity facility for tracking filesystem metadata blocks |
| 387 | within internal data structures. This allows multi- |
| 388 | block allocator and other routines to quickly locate |
| 389 | extents which might overlap with filesystem metadata |
| 390 | blocks. This option is intended for debugging |
| 391 | purposes and since it negatively affects the |
| 392 | performance, it is off by default. |
| 393 | |
| 394 | dioread_lock Controls whether or not ext4 should use the DIO read |
| 395 | dioread_nolock locking. If the dioread_nolock option is specified |
| 396 | ext4 will allocate uninitialized extent before buffer |
| 397 | write and convert the extent to initialized after IO |
| 398 | completes. This approach allows ext4 code to avoid |
| 399 | using inode mutex, which improves scalability on high |
| 400 | speed storages. However this does not work with nobh |
| 401 | option and the mount will fail. Nor does it work with |
| 402 | data journaling and dioread_nolock option will be |
| 403 | ignored with kernel warning. Note that dioread_nolock |
| 404 | code path is only used for extent-based files. |
| 405 | Because of the restrictions this options comprises |
| 406 | it is off by default (e.g. dioread_lock). |
| 407 | |
| 408 | i_version Enable 64-bit inode version support. This option is |
| 409 | off by default. |
| 410 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 411 | Data Mode |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 412 | ========= |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 413 | There are 3 different data modes: |
| 414 | |
| 415 | * writeback mode |
| 416 | In data=writeback mode, ext4 does not journal data at all. This mode provides |
| 417 | a similar level of journaling as that of XFS, JFS, and ReiserFS in its default |
| 418 | mode - metadata journaling. A crash+recovery can cause incorrect data to |
| 419 | appear in files which were written shortly before the crash. This mode will |
| 420 | typically provide the best ext4 performance. |
| 421 | |
| 422 | * ordered mode |
| 423 | In data=ordered mode, ext4 only officially journals metadata, but it logically |
Mingming Cao | 49f1487 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 424 | groups metadata information related to data changes with the data blocks into a |
| 425 | single unit called a transaction. When it's time to write the new metadata |
| 426 | out to disk, the associated data blocks are written first. In general, |
| 427 | this mode performs slightly slower than writeback but significantly faster than journal mode. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 428 | |
| 429 | * journal mode |
| 430 | data=journal mode provides full data and metadata journaling. All new data is |
| 431 | written to the journal first, and then to its final location. |
| 432 | In the event of a crash, the journal can be replayed, bringing both data and |
| 433 | metadata into a consistent state. This mode is the slowest except when data |
| 434 | needs to be read from and written to disk at the same time where it |
Matt LaPlante | 19f5946 | 2009-04-27 15:06:31 +0200 | [diff] [blame] | 435 | outperforms all others modes. Currently ext4 does not have delayed |
Mingming Cao | 49f1487 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 436 | allocation support if this data journalling mode is selected. |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 437 | |
Lukas Czerner | 6f9524e | 2011-02-21 20:16:21 -0500 | [diff] [blame] | 438 | /proc entries |
| 439 | ============= |
| 440 | |
| 441 | Information about mounted ext4 file systems can be found in |
| 442 | /proc/fs/ext4. Each mounted filesystem will have a directory in |
| 443 | /proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or |
| 444 | /proc/fs/ext4/dm-0). The files in each per-device directory are shown |
| 445 | in table below. |
| 446 | |
| 447 | Files in /proc/fs/ext4/<devname> |
| 448 | .............................................................................. |
| 449 | File Content |
| 450 | mb_groups details of multiblock allocator buddy cache of free blocks |
| 451 | .............................................................................. |
| 452 | |
| 453 | /sys entries |
| 454 | ============ |
| 455 | |
| 456 | Information about mounted ext4 file systems can be found in |
| 457 | /sys/fs/ext4. Each mounted filesystem will have a directory in |
| 458 | /sys/fs/ext4 based on its device name (i.e., /sys/fs/ext4/hdc or |
| 459 | /sys/fs/ext4/dm-0). The files in each per-device directory are shown |
| 460 | in table below. |
| 461 | |
| 462 | Files in /sys/fs/ext4/<devname> |
| 463 | (see also Documentation/ABI/testing/sysfs-fs-ext4) |
| 464 | .............................................................................. |
| 465 | File Content |
| 466 | |
| 467 | delayed_allocation_blocks This file is read-only and shows the number of |
| 468 | blocks that are dirty in the page cache, but |
| 469 | which do not have their location in the |
| 470 | filesystem allocated yet. |
| 471 | |
| 472 | inode_goal Tuning parameter which (if non-zero) controls |
| 473 | the goal inode used by the inode allocator in |
| 474 | preference to all other allocation heuristics. |
| 475 | This is intended for debugging use only, and |
| 476 | should be 0 on production systems. |
| 477 | |
| 478 | inode_readahead_blks Tuning parameter which controls the maximum |
| 479 | number of inode table blocks that ext4's inode |
| 480 | table readahead algorithm will pre-read into |
| 481 | the buffer cache |
| 482 | |
| 483 | lifetime_write_kbytes This file is read-only and shows the number of |
| 484 | kilobytes of data that have been written to this |
| 485 | filesystem since it was created. |
| 486 | |
| 487 | max_writeback_mb_bump The maximum number of megabytes the writeback |
| 488 | code will try to write out before move on to |
| 489 | another inode. |
| 490 | |
| 491 | mb_group_prealloc The multiblock allocator will round up allocation |
| 492 | requests to a multiple of this tuning parameter if |
| 493 | the stripe size is not set in the ext4 superblock |
| 494 | |
| 495 | mb_max_to_scan The maximum number of extents the multiblock |
| 496 | allocator will search to find the best extent |
| 497 | |
| 498 | mb_min_to_scan The minimum number of extents the multiblock |
| 499 | allocator will search to find the best extent |
| 500 | |
| 501 | mb_order2_req Tuning parameter which controls the minimum size |
| 502 | for requests (as a power of 2) where the buddy |
| 503 | cache is used |
| 504 | |
| 505 | mb_stats Controls whether the multiblock allocator should |
| 506 | collect statistics, which are shown during the |
| 507 | unmount. 1 means to collect statistics, 0 means |
| 508 | not to collect statistics |
| 509 | |
| 510 | mb_stream_req Files which have fewer blocks than this tunable |
| 511 | parameter will have their blocks allocated out |
| 512 | of a block group specific preallocation pool, so |
| 513 | that small files are packed closely together. |
| 514 | Each large file will have its blocks allocated |
| 515 | out of its own unique preallocation pool. |
| 516 | |
| 517 | session_write_kbytes This file is read-only and shows the number of |
| 518 | kilobytes of data that have been written to this |
| 519 | filesystem since it was mounted. |
| 520 | .............................................................................. |
| 521 | |
| 522 | Ioctls |
| 523 | ====== |
| 524 | |
| 525 | There is some Ext4 specific functionality which can be accessed by applications |
| 526 | through the system call interfaces. The list of all Ext4 specific ioctls are |
| 527 | shown in the table below. |
| 528 | |
| 529 | Table of Ext4 specific ioctls |
| 530 | .............................................................................. |
| 531 | Ioctl Description |
| 532 | EXT4_IOC_GETFLAGS Get additional attributes associated with inode. |
| 533 | The ioctl argument is an integer bitfield, with |
| 534 | bit values described in ext4.h. This ioctl is an |
| 535 | alias for FS_IOC_GETFLAGS. |
| 536 | |
| 537 | EXT4_IOC_SETFLAGS Set additional attributes associated with inode. |
| 538 | The ioctl argument is an integer bitfield, with |
| 539 | bit values described in ext4.h. This ioctl is an |
| 540 | alias for FS_IOC_SETFLAGS. |
| 541 | |
| 542 | EXT4_IOC_GETVERSION |
| 543 | EXT4_IOC_GETVERSION_OLD |
| 544 | Get the inode i_generation number stored for |
| 545 | each inode. The i_generation number is normally |
| 546 | changed only when new inode is created and it is |
| 547 | particularly useful for network filesystems. The |
| 548 | '_OLD' version of this ioctl is an alias for |
| 549 | FS_IOC_GETVERSION. |
| 550 | |
| 551 | EXT4_IOC_SETVERSION |
| 552 | EXT4_IOC_SETVERSION_OLD |
| 553 | Set the inode i_generation number stored for |
| 554 | each inode. The '_OLD' version of this ioctl |
| 555 | is an alias for FS_IOC_SETVERSION. |
| 556 | |
| 557 | EXT4_IOC_GROUP_EXTEND This ioctl has the same purpose as the resize |
| 558 | mount option. It allows to resize filesystem |
| 559 | to the end of the last existing block group, |
| 560 | further resize has to be done with resize2fs, |
| 561 | either online, or offline. The argument points |
| 562 | to the unsigned logn number representing the |
| 563 | filesystem new block count. |
| 564 | |
| 565 | EXT4_IOC_MOVE_EXT Move the block extents from orig_fd (the one |
| 566 | this ioctl is pointing to) to the donor_fd (the |
| 567 | one specified in move_extent structure passed |
| 568 | as an argument to this ioctl). Then, exchange |
| 569 | inode metadata between orig_fd and donor_fd. |
| 570 | This is especially useful for online |
| 571 | defragmentation, because the allocator has the |
| 572 | opportunity to allocate moved blocks better, |
| 573 | ideally into one contiguous extent. |
| 574 | |
| 575 | EXT4_IOC_GROUP_ADD Add a new group descriptor to an existing or |
| 576 | new group descriptor block. The new group |
| 577 | descriptor is described by ext4_new_group_input |
| 578 | structure, which is passed as an argument to |
| 579 | this ioctl. This is especially useful in |
| 580 | conjunction with EXT4_IOC_GROUP_EXTEND, |
| 581 | which allows online resize of the filesystem |
| 582 | to the end of the last existing block group. |
| 583 | Those two ioctls combined is used in userspace |
| 584 | online resize tool (e.g. resize2fs). |
| 585 | |
| 586 | EXT4_IOC_MIGRATE This ioctl operates on the filesystem itself. |
| 587 | It converts (migrates) ext3 indirect block mapped |
| 588 | inode to ext4 extent mapped inode by walking |
| 589 | through indirect block mapping of the original |
| 590 | inode and converting contiguous block ranges |
| 591 | into ext4 extents of the temporary inode. Then, |
| 592 | inodes are swapped. This ioctl might help, when |
| 593 | migrating from ext3 to ext4 filesystem, however |
| 594 | suggestion is to create fresh ext4 filesystem |
| 595 | and copy data from the backup. Note, that |
| 596 | filesystem has to support extents for this ioctl |
| 597 | to work. |
| 598 | |
| 599 | EXT4_IOC_ALLOC_DA_BLKS Force all of the delay allocated blocks to be |
| 600 | allocated to preserve application-expected ext3 |
| 601 | behaviour. Note that this will also start |
| 602 | triggering a write of the data blocks, but this |
| 603 | behaviour may change in the future as it is |
| 604 | not necessary and has been done this way only |
| 605 | for sake of simplicity. |
| 606 | .............................................................................. |
| 607 | |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 608 | References |
| 609 | ========== |
| 610 | |
| 611 | kernel source: <file:fs/ext4/> |
| 612 | <file:fs/jbd2/> |
| 613 | |
| 614 | programs: http://e2fsprogs.sourceforge.net/ |
Dave Kleikamp | fc513a3 | 2006-10-11 01:21:25 -0700 | [diff] [blame] | 615 | |
| 616 | useful links: http://fedoraproject.org/wiki/ext3-devel |
| 617 | http://www.bullopensource.org/ext4/ |
Jose R. Santos | 93e3270 | 2008-07-11 19:27:31 -0400 | [diff] [blame] | 618 | http://ext4.wiki.kernel.org/index.php/Main_Page |
| 619 | http://fedoraproject.org/wiki/Features/Ext4 |