Documentation/filesystems/ntfs.txt

   1 The Linux NTFS filesystem driver
   2 ================================
   3
   4
   5 Table of contents
   6 =================
   7
   8 - Overview
   9 - Web site
  10 - Features
  11 - Supported mount options
  12 - Known bugs and (mis-)features
  13 - Using Software RAID with NTFS
  14 - Limitiations when using the MD driver
  15 - ChangeLog
  16
  17
  18 Overview
  19 ========
  20
  21 Linux-NTFS comes with a number of user-space programs known as ntfsprogs.
  22 These include mkntfs, a full-featured ntfs file system format utility,
  23 ntfsundelete used for recovering files that were unintentionally deleted
  24 from an NTFS volume and ntfsresize which is used to resize an NTFS partition.
  25 See the web site for more information.
  26
  27 To mount an NTFS 1.2/3.x (Windows NT4/2000/XP/2003) volume, use the file
  28 system type 'ntfs'.  The driver currently supports read-only mode (with no
  29 fault-tolerance, encryption or journalling) and very limited, but safe, write
  30 support.
  31
  32 For fault tolerance and raid support (i.e. volume and stripe sets), you can
  33 use the kernel's Software RAID / MD driver.  See section "Using Software RAID
  34 with NTFS" for details.
  35
  36
  37 Web site
  38 ========
  39
  40 There is plenty of additional information on the linux-ntfs web site
  41 at http://linux-ntfs.sourceforge.net/
  42
  43 The web site has a lot of additional information, such as a comprehensive
  44 FAQ, documentation on the NTFS on-disk format, informaiton on the Linux-NTFS
  45 userspace utilities, etc.
  46
  47
  48 Features
  49 ========
  50
  51 - This is a complete rewrite of the NTFS driver that used to be in the kernel.
  52   This new driver implements NTFS read support and is functionally equivalent
  53   to the old ntfs driver.
  54 - The new driver has full support for sparse files on NTFS 3.x volumes which
  55   the old driver isn't happy with.
  56 - The new driver supports execution of binaries due to mmap() now being
  57   supported.
  58 - The new driver supports loopback mounting of files on NTFS which is used by
  59   some Linux distributions to enable the user to run Linux from an NTFS
  60   partition by creating a large file while in Windows and then loopback
  61   mounting the file while in Linux and creating a Linux filesystem on it that
  62   is used to install Linux on it.
  63 - A comparison of the two drivers using:
  64         time find . -type f -exec md5sum "{}" \;
  65   run three times in sequence with each driver (after a reboot) on a 1.4GiB
  66   NTFS partition, showed the new driver to be 20% faster in total time elapsed
  67   (from 9:43 minutes on average down to 7:53).  The time spent in user space
  68   was unchanged but the time spent in the kernel was decreased by a factor of
  69   2.5 (from 85 CPU seconds down to 33).
  70 - The driver does not support short file names in general.  For backwards
  71   compatibility, we implement access to files using their short file names if
  72   they exist.  The driver will not create short file names however, and a
  73   rename will discard any existing short file name.
  74 - The new driver supports exporting of mounted NTFS volumes via NFS.
  75 - The new driver supports async io (aio).
  76 - The new driver supports fsync(2), fdatasync(2), and msync(2).
  77 - The new driver supports readv(2) and writev(2).
  78 - The new driver supports access time updates (including mtime and ctime).
  79
  80
  81 Supported mount options
  82 =======================
  83
  84 In addition to the generic mount options described by the manual page for the
  85 mount command (man 8 mount, also see man 5 fstab), the NTFS driver supports the
  86 following mount options:
  87
  88 iocharset=name          Deprecated option.  Still supported but please use
  89                         nls=name in the future.  See description for nls=name.
  90
  91 nls=name                Character set to use when returning file names.
  92                         Unlike VFAT, NTFS suppresses names that contain
  93                         unconvertible characters.  Note that most character
  94                         sets contain insufficient characters to represent all
  95                         possible Unicode characters that can exist on NTFS.
  96                         To be sure you are not missing any files, you are
  97                         advised to use nls=utf8 which is capable of
  98                         representing all Unicode characters.
  99
 100 utf8=<bool>             Option no longer supported.  Currently mapped to
 101                         nls=utf8 but please use nls=utf8 in the future and
 102                         make sure utf8 is compiled either as module or into
 103                         the kernel.  See description for nls=name.
 104
 105 uid=
 106 gid=
 107 umask=                  Provide default owner, group, and access mode mask.
 108                         These options work as documented in mount(8).  By
 109                         default, the files/directories are owned by root and
 110                         he/she has read and write permissions, as well as
 111                         browse permission for directories.  No one else has any
 112                         access permissions.  I.e. the mode on all files is by
 113                         default rw------- and for directories rwx------, a
 114                         consequence of the default fmask=0177 and dmask=0077.
 115                         Using a umask of zero will grant all permissions to
 116                         everyone, i.e. all files and directories will have mode
 117                         rwxrwxrwx.
 118
 119 fmask=
 120 dmask=                  Instead of specifying umask which applies both to
 121                         files and directories, fmask applies only to files and
 122                         dmask only to directories.
 123
 124 sloppy=<BOOL>           If sloppy is specified, ignore unknown mount options.
 125                         Otherwise the default behaviour is to abort mount if
 126                         any unknown options are found.
 127
 128 show_sys_files=<BOOL>   If show_sys_files is specified, show the system files
 129                         in directory listings.  Otherwise the default behaviour
 130                         is to hide the system files.
 131                         Note that even when show_sys_files is specified, "$MFT"
 132                         will not be visible due to bugs/mis-features in glibc.
 133                         Further, note that irrespective of show_sys_files, all
 134                         files are accessible by name, i.e. you can always do
 135                         "ls -l \$UpCase" for example to specifically show the
 136                         system file containing the Unicode upcase table.
 137
 138 case_sensitive=<BOOL>   If case_sensitive is specified, treat all file names as
 139                         case sensitive and create file names in the POSIX
 140                         namespace.  Otherwise the default behaviour is to treat
 141                         file names as case insensitive and to create file names
 142                         in the WIN32/LONG name space.  Note, the Linux NTFS
 143                         driver will never create short file names and will
 144                         remove them on rename/delete of the corresponding long
 145                         file name.
 146                         Note that files remain accessible via their short file
 147                         name, if it exists.  If case_sensitive, you will need
 148                         to provide the correct case of the short file name.
 149
 150 errors=opt              What to do when critical file system errors are found.
 151                         Following values can be used for "opt":
 152                           continue: DEFAULT, try to clean-up as much as
 153                                     possible, e.g. marking a corrupt inode as
 154                                     bad so it is no longer accessed, and then
 155                                     continue.
 156                           recover:  At present only supported is recovery of
 157                                     the boot sector from the backup copy.
 158                                     If read-only mount, the recovery is done
 159                                     in memory only and not written to disk.
 160                         Note that the options are additive, i.e. specifying:
 161                            errors=continue,errors=recover
 162                         means the driver will attempt to recover and if that
 163                         fails it will clean-up as much as possible and
 164                         continue.
 165
 166 mft_zone_multiplier=    Set the MFT zone multiplier for the volume (this
 167                         setting is not persistent across mounts and can be
 168                         changed from mount to mount but cannot be changed on
 169                         remount).  Values of 1 to 4 are allowed, 1 being the
 170                         default.  The MFT zone multiplier determines how much
 171                         space is reserved for the MFT on the volume.  If all
 172                         other space is used up, then the MFT zone will be
 173                         shrunk dynamically, so this has no impact on the
 174                         amount of free space.  However, it can have an impact
 175                         on performance by affecting fragmentation of the MFT.
 176                         In general use the default.  If you have a lot of small
 177                         files then use a higher value.  The values have the
 178                         following meaning:
 179                               Value          MFT zone size (% of volume size)
 180                                 1               12.5%
 181                                 2               25%
 182                                 3               37.5%
 183                                 4               50%
 184                         Note this option is irrelevant for read-only mounts.
 185
 186
 187 Known bugs and (mis-)features
 188 =============================
 189
 190 - The link count on each directory inode entry is set to 1, due to Linux not
 191   supporting directory hard links.  This may well confuse some user space
 192   applications, since the directory names will have the same inode numbers.
 193   This also speeds up ntfs_read_inode() immensely.  And we haven't found any
 194   problems with this approach so far.  If you find a problem with this, please
 195   let us know.
 196
 197
 198 Please send bug reports/comments/feedback/abuse to the Linux-NTFS development
 199 list at sourceforge: linux-ntfs-dev@lists.sourceforge.net
 200
 201
 202 Using Software RAID with NTFS
 203 =============================
 204
 205 For support of volume and stripe sets, use the kernel's Software RAID / MD
 206 driver and set up your /etc/raidtab appropriately (see man 5 raidtab).
 207
 208 Linear volume sets, i.e. linear raid, as well as stripe sets, i.e. raid level
 209 0, have been tested and work fine (though see section "Limitiations when using
 210 the MD driver with NTFS volumes" especially if you want to use linear raid).
 211 Even though untested, there is no reason why mirrors, i.e. raid level 1, and
 212 stripes with parity, i.e. raid level 5, should not work, too.
 213
 214 You have to use the "persistent-superblock 0" option for each raid-disk in the
 215 NTFS volume/stripe you are configuring in /etc/raidtab as the persistent
 216 superblock used by the MD driver would damange the NTFS volume.
 217
 218 Windows by default uses a stripe chunk size of 64k, so you probably want the
 219 "chunk-size 64k" option for each raid-disk, too.
 220
 221 For example, if you have a stripe set consisting of two partitions /dev/hda5
 222 and /dev/hdb1 your /etc/raidtab would look like this:
 223
 224 raiddev /dev/md0
 225         raid-level      0
 226         nr-raid-disks   2
 227         nr-spare-disks  0
 228         persistent-superblock   0
 229         chunk-size      64k
 230         device          /dev/hda5
 231         raid-disk       0
 232         device          /dev/hdb1
 233         raid-disl       1
 234
 235 For linear raid, just change the raid-level above to "raid-level linear", for
 236 mirrors, change it to "raid-level 1", and for stripe sets with parity, change
 237 it to "raid-level 5".
 238
 239 Note for stripe sets with parity you will also need to tell the MD driver
 240 which parity algorithm to use by specifying the option "parity-algorithm
 241 which", where you need to replace "which" with the name of the algorithm to
 242 use (see man 5 raidtab for available algorithms) and you will have to try the
 243 different available algorithms until you find one that works.  Make sure you
 244 are working read-only when playing with this as you may damage your data
 245 otherwise.  If you find which algorithm works please let us know (email the
 246 linux-ntfs developers list linux-ntfs-dev@lists.sourceforge.net or drop in on
 247 IRC in channel #ntfs on the irc.freenode.net network) so we can update this
 248 documentation.
 249
 250 Once the raidtab is setup, run for example raid0run -a to start all devices or
 251 raid0run /dev/md0 to start a particular md device, in this case /dev/md0.
 252
 253 Then just use the mount command as usual to mount the ntfs volume using for
 254 example:        mount -t ntfs -o ro /dev/md0 /mnt/myntfsvolume
 255
 256 It is advisable to do the mount read-only to see if the md volume has been
 257 setup correctly to avoid the possibility of causing damage to the data on the
 258 ntfs volume.
 259
 260
 261 Limitiations when using the MD driver
 262 =====================================
 263
 264 Using the md driver will not work properly if any of your NTFS partitions have
 265 an odd number of sectors.  This is especially important for linear raid as all
 266 data after the first partition with an odd number of sectors will be offset by
 267 one or more sectors so if you mount such a partition with write support you
 268 will cause massive damage to the data on the volume which will only become
 269 apparent when you try to use the volume again under Windows.
 270
 271 So when using linear raid, make sure that all your partitions have an even
 272 number of sectors BEFORE attempting to use it.  You have been warned!
 273
 274
 275 ChangeLog
 276 =========
 277
 278 Note, a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog.
 279
 280 2.1.20:
 281         - Fix two stupid bugs introduced in 2.1.18 release.
 282 2.1.19:
 283         - Minor bugfix in handling of the default upcase table.
 284         - Many internal cleanups and improvements.  Many thanks to Linus
 285           Torvalds and Al Viro for the help and advice with the sparse
 286           annotations and cleanups.
 287 2.1.18:
 288         - Fix scheduling latencies at mount time.  (Ingo Molnar)
 289         - Fix endianness bug in a little traversed portion of the attribute
 290           lookup code.
 291 2.1.17:
 292         - Fix bugs in mount time error code paths.
 293 2.1.16:
 294         - Implement access time updates (including mtime and ctime).
 295         - Implement fsync(2), fdatasync(2), and msync(2) system calls.
 296         - Enable the readv(2) and writev(2) system calls.
 297         - Enable access via the asynchronous io (aio) API by adding support for
 298           the aio_read(3) and aio_write(3) functions.
 299 2.1.15:
 300         - Invalidate quotas when (re)mounting read-write.
 301           NOTE:  This now only leave user space journalling on the side.  (See
 302           note for version 2.1.13, below.)
 303 2.1.14:
 304         - Fix an NFSd caused deadlock reported by several users.
 305 2.1.13:
 306         - Implement writing of inodes (access time updates are not implemented
 307           yet so mounting with -o noatime,nodiratime is enforced).
 308         - Enable writing out of resident files so you can now overwrite any
 309           uncompressed, unencrypted, nonsparse file as long as you do not
 310           change the file size.
 311         - Add housekeeping of ntfs system files so that ntfsfix no longer needs
 312           to be run after writing to an NTFS volume.
 313           NOTE:  This still leaves quota tracking and user space journalling on
 314           the side but they should not cause data corruption.  In the worst
 315           case the charged quotas will be out of date ($Quota) and some
 316           userspace applications might get confused due to the out of date
 317           userspace journal ($UsnJrnl).
 318 2.1.12:
 319         - Fix the second fix to the decompression engine from the 2.1.9 release
 320           and some further internals cleanups.
 321 2.1.11:
 322         - Driver internal cleanups.
 323 2.1.10:
 324         - Force read-only (re)mounting of volumes with unsupported volume
 325           flags and various cleanups.
 326 2.1.9:
 327         - Fix two bugs in handling of corner cases in the decompression engine.
 328 2.1.8:
 329         - Read the $MFT mirror and compare it to the $MFT and if the two do not
 330           match, force a read-only mount and do not allow read-write remounts.
 331         - Read and parse the $LogFile journal and if it indicates that the
 332           volume was not shutdown cleanly, force a read-only mount and do not
 333           allow read-write remounts.  If the $LogFile indicates a clean
 334           shutdown and a read-write (re)mount is requested, empty $LogFile to
 335           ensure that Windows cannot cause data corruption by replaying a stale
 336           journal after Linux has written to the volume.
 337         - Improve time handling so that the NTFS time is fully preserved when
 338           converted to kernel time and only up to 99 nano-seconds are lost when
 339           kernel time is converted to NTFS time.
 340 2.1.7:
 341         - Enable NFS exporting of mounted NTFS volumes.
 342 2.1.6:
 343         - Fix minor bug in handling of compressed directories that fixes the
 344           erroneous "du" and "stat" output people reported.
 345 2.1.5:
 346         - Minor bug fix in attribute list attribute handling that fixes the
 347           I/O errors on "ls" of certain fragmented files found by at least two
 348           people running Windows XP.
 349 2.1.4:
 350         - Minor update allowing compilation with all gcc versions (well, the
 351           ones the kernel can be compiled with anyway).
 352 2.1.3:
 353         - Major bug fixes for reading files and volumes in corner cases which
 354           were being hit by Windows 2k/XP users.
 355 2.1.2:
 356         - Major bug fixes aleviating the hangs in statfs experienced by some
 357           users.
 358 2.1.1:
 359         - Update handling of compressed files so people no longer get the
 360           frequently reported warning messages about initialized_size !=
 361           data_size.
 362 2.1.0:
 363         - Add configuration option for developmental write support.
 364         - Initial implementation of file overwriting. (Writes to resident files
 365           are not written out to disk yet, so avoid writing to files smaller
 366           than about 1kiB.)
 367         - Intercept/abort changes in file size as they are not implemented yet.
 368 2.0.25:
 369         - Minor bugfixes in error code paths and small cleanups.
 370 2.0.24:
 371         - Small internal cleanups.
 372         - Support for sendfile system call. (Christoph Hellwig)
 373 2.0.23:
 374         - Massive internal locking changes to mft record locking. Fixes
 375           various race conditions and deadlocks.
 376         - Fix ntfs over loopback for compressed files by adding an
 377           optimization barrier. (gcc was screwing up otherwise ?)
 378         Thanks go to Christoph Hellwig for pointing these two out:
 379         - Remove now unused function fs/ntfs/malloc.h::vmalloc_nofs().
 380         - Fix ntfs_free() for ia64 and parisc.
 381 2.0.22:
 382         - Small internal cleanups.
 383 2.0.21:
 384         These only affect 32-bit architectures:
 385         - Check for, and refuse to mount too large volumes (maximum is 2TiB).
 386         - Check for, and refuse to open too large files and directories
 387           (maximum is 16TiB).
 388 2.0.20:
 389         - Support non-resident directory index bitmaps. This means we now cope
 390           with huge directories without problems.
 391         - Fix a page leak that manifested itself in some cases when reading
 392           directory contents.
 393         - Internal cleanups.
 394 2.0.19:
 395         - Fix race condition and improvements in block i/o interface.
 396         - Optimization when reading compressed files.
 397 2.0.18:
 398         - Fix race condition in reading of compressed files.
 399 2.0.17:
 400         - Cleanups and optimizations.
 401 2.0.16:
 402         - Fix stupid bug introduced in 2.0.15 in new attribute inode API.
 403         - Big internal cleanup replacing the mftbmp access hacks by using the
 404           new attribute inode API instead.
 405 2.0.15:
 406         - Bug fix in parsing of remount options.
 407         - Internal changes implementing attribute (fake) inodes allowing all
 408           attribute i/o to go via the page cache and to use all the normal
 409           vfs/mm functionality.
 410 2.0.14:
 411         - Internal changes improving run list merging code and minor locking
 412           change to not rely on BKL in ntfs_statfs().
 413 2.0.13:
 414         - Internal changes towards using iget5_locked() in preparation for
 415           fake inodes and small cleanups to ntfs_volume structure.
 416 2.0.12:
 417         - Internal cleanups in address space operations made possible by the
 418           changes introduced in the previous release.
 419 2.0.11:
 420         - Internal updates and cleanups introducing the first step towards
 421           fake inode based attribute i/o.
 422 2.0.10:
 423         - Microsoft says that the maximum number of inodes is 2^32 - 1. Update
 424           the driver accordingly to only use 32-bits to store inode numbers on
 425           32-bit architectures. This improves the speed of the driver a little.
 426 2.0.9:
 427         - Change decompression engine to use a single buffer. This should not
 428           affect performance except perhaps on the most heavy i/o on SMP
 429           systems when accessing multiple compressed files from multiple
 430           devices simultaneously.
 431         - Minor updates and cleanups.
 432 2.0.8:
 433         - Remove now obsolete show_inodes and posix mount option(s).
 434         - Restore show_sys_files mount option.
 435         - Add new mount option case_sensitive, to determine if the driver
 436           treats file names as case sensitive or not.
 437         - Mostly drop support for short file names (for backwards compatibility
 438           we only support accessing files via their short file name if one
 439           exists).
 440         - Fix dcache aliasing issues wrt short/long file names.
 441         - Cleanups and minor fixes.
 442 2.0.7:
 443         - Just cleanups.
 444 2.0.6:
 445         - Major bugfix to make compatible with other kernel changes. This fixes
 446           the hangs/oopses on umount.
 447         - Locking cleanup in directory operations (remove BKL usage).
 448 2.0.5:
 449         - Major buffer overflow bug fix.
 450         - Minor cleanups and updates for kernel 2.5.12.
 451 2.0.4:
 452         - Cleanups and updates for kernel 2.5.11.
 453 2.0.3:
 454         - Small bug fixes, cleanups, and performance improvements.
 455 2.0.2:
 456         - Use default fmask of 0177 so that files are no executable by default.
 457           If you want owner executable files, just use fmask=0077.
 458         - Update for kernel 2.5.9 but preserve backwards compatibility with
 459           kernel 2.5.7.
 460         - Minor bug fixes, cleanups, and updates.
 461 2.0.1:
 462         - Minor updates, primarily set the executable bit by default on files
 463           so they can be executed.
 464 2.0.0:
 465         - Started ChangeLog.
 466