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 NTFS volume and stripe sets
  14   - The Device-Mapper driver
  15   - The Software RAID / MD driver
  16   - Limitations when using the MD driver
  17
  18
  19 Overview
  20 ========
  21
  22 Linux-NTFS comes with a number of user-space programs known as ntfsprogs.
  23 These include mkntfs, a full-featured ntfs filesystem format utility,
  24 ntfsundelete used for recovering files that were unintentionally deleted
  25 from an NTFS volume and ntfsresize which is used to resize an NTFS partition.
  26 See the web site for more information.
  27
  28 To mount an NTFS 1.2/3.x (Windows NT4/2000/XP/2003) volume, use the file
  29 system type 'ntfs'.  The driver currently supports read-only mode (with no
  30 fault-tolerance, encryption or journalling) and very limited, but safe, write
  31 support.
  32
  33 For fault tolerance and raid support (i.e. volume and stripe sets), you can
  34 use the kernel's Software RAID / MD driver.  See section "Using Software RAID
  35 with NTFS" for details.
  36
  37
  38 Web site
  39 ========
  40
  41 There is plenty of additional information on the linux-ntfs web site
  42 at http://www.linux-ntfs.org/
  43
  44 The web site has a lot of additional information, such as a comprehensive
  45 FAQ, documentation on the NTFS on-disk format, information on the Linux-NTFS
  46 userspace utilities, etc.
  47
  48
  49 Features
  50 ========
  51
  52 - This is a complete rewrite of the NTFS driver that used to be in the 2.4 and
  53   earlier kernels.  This new driver implements NTFS read support and is
  54   functionally equivalent to the old ntfs driver and it also implements limited
  55   write support.  The biggest limitation at present is that files/directories
  56   cannot be created or deleted.  See below for the list of write features that
  57   are so far supported.  Another limitation is that writing to compressed files
  58   is not implemented at all.  Also, neither read nor write access to encrypted
  59   files is so far implemented.
  60 - The new driver has full support for sparse files on NTFS 3.x volumes which
  61   the old driver isn't happy with.
  62 - The new driver supports execution of binaries due to mmap() now being
  63   supported.
  64 - The new driver supports loopback mounting of files on NTFS which is used by
  65   some Linux distributions to enable the user to run Linux from an NTFS
  66   partition by creating a large file while in Windows and then loopback
  67   mounting the file while in Linux and creating a Linux filesystem on it that
  68   is used to install Linux on it.
  69 - A comparison of the two drivers using:
  70         time find . -type f -exec md5sum "{}" \;
  71   run three times in sequence with each driver (after a reboot) on a 1.4GiB
  72   NTFS partition, showed the new driver to be 20% faster in total time elapsed
  73   (from 9:43 minutes on average down to 7:53).  The time spent in user space
  74   was unchanged but the time spent in the kernel was decreased by a factor of
  75   2.5 (from 85 CPU seconds down to 33).
  76 - The driver does not support short file names in general.  For backwards
  77   compatibility, we implement access to files using their short file names if
  78   they exist.  The driver will not create short file names however, and a
  79   rename will discard any existing short file name.
  80 - The new driver supports exporting of mounted NTFS volumes via NFS.
  81 - The new driver supports async io (aio).
  82 - The new driver supports fsync(2), fdatasync(2), and msync(2).
  83 - The new driver supports readv(2) and writev(2).
  84 - The new driver supports access time updates (including mtime and ctime).
  85 - The new driver supports truncate(2) and open(2) with O_TRUNC.  But at present
  86   only very limited support for highly fragmented files, i.e. ones which have
  87   their data attribute split across multiple extents, is included.  Another
  88   limitation is that at present truncate(2) will never create sparse files,
  89   since to mark a file sparse we need to modify the directory entry for the
  90   file and we do not implement directory modifications yet.
  91 - The new driver supports write(2) which can both overwrite existing data and
  92   extend the file size so that you can write beyond the existing data.  Also,
  93   writing into sparse regions is supported and the holes are filled in with
  94   clusters.  But at present only limited support for highly fragmented files,
  95   i.e. ones which have their data attribute split across multiple extents, is
  96   included.  Another limitation is that write(2) will never create sparse
  97   files, since to mark a file sparse we need to modify the directory entry for
  98   the file and we do not implement directory modifications yet.
  99
 100 Supported mount options
 101 =======================
 102
 103 In addition to the generic mount options described by the manual page for the
 104 mount command (man 8 mount, also see man 5 fstab), the NTFS driver supports the
 105 following mount options:
 106
 107 iocharset=name          Deprecated option.  Still supported but please use
 108                         nls=name in the future.  See description for nls=name.
 109
 110 nls=name                Character set to use when returning file names.
 111                         Unlike VFAT, NTFS suppresses names that contain
 112                         unconvertible characters.  Note that most character
 113                         sets contain insufficient characters to represent all
 114                         possible Unicode characters that can exist on NTFS.
 115                         To be sure you are not missing any files, you are
 116                         advised to use nls=utf8 which is capable of
 117                         representing all Unicode characters.
 118
 119 utf8=<bool>             Option no longer supported.  Currently mapped to
 120                         nls=utf8 but please use nls=utf8 in the future and
 121                         make sure utf8 is compiled either as module or into
 122                         the kernel.  See description for nls=name.
 123
 124 uid=
 125 gid=
 126 umask=                  Provide default owner, group, and access mode mask.
 127                         These options work as documented in mount(8).  By
 128                         default, the files/directories are owned by root and
 129                         he/she has read and write permissions, as well as
 130                         browse permission for directories.  No one else has any
 131                         access permissions.  I.e. the mode on all files is by
 132                         default rw------- and for directories rwx------, a
 133                         consequence of the default fmask=0177 and dmask=0077.
 134                         Using a umask of zero will grant all permissions to
 135                         everyone, i.e. all files and directories will have mode
 136                         rwxrwxrwx.
 137
 138 fmask=
 139 dmask=                  Instead of specifying umask which applies both to
 140                         files and directories, fmask applies only to files and
 141                         dmask only to directories.
 142
 143 sloppy=<BOOL>           If sloppy is specified, ignore unknown mount options.
 144                         Otherwise the default behaviour is to abort mount if
 145                         any unknown options are found.
 146
 147 show_sys_files=<BOOL>   If show_sys_files is specified, show the system files
 148                         in directory listings.  Otherwise the default behaviour
 149                         is to hide the system files.
 150                         Note that even when show_sys_files is specified, "$MFT"
 151                         will not be visible due to bugs/mis-features in glibc.
 152                         Further, note that irrespective of show_sys_files, all
 153                         files are accessible by name, i.e. you can always do
 154                         "ls -l \$UpCase" for example to specifically show the
 155                         system file containing the Unicode upcase table.
 156
 157 case_sensitive=<BOOL>   If case_sensitive is specified, treat all file names as
 158                         case sensitive and create file names in the POSIX
 159                         namespace.  Otherwise the default behaviour is to treat
 160                         file names as case insensitive and to create file names
 161                         in the WIN32/LONG name space.  Note, the Linux NTFS
 162                         driver will never create short file names and will
 163                         remove them on rename/delete of the corresponding long
 164                         file name.
 165                         Note that files remain accessible via their short file
 166                         name, if it exists.  If case_sensitive, you will need
 167                         to provide the correct case of the short file name.
 168
 169 disable_sparse=<BOOL>   If disable_sparse is specified, creation of sparse
 170                         regions, i.e. holes, inside files is disabled for the
 171                         volume (for the duration of this mount only).  By
 172                         default, creation of sparse regions is enabled, which
 173                         is consistent with the behaviour of traditional Unix
 174                         filesystems.
 175
 176 errors=opt              What to do when critical filesystem errors are found.
 177                         Following values can be used for "opt":
 178                           continue: DEFAULT, try to clean-up as much as
 179                                     possible, e.g. marking a corrupt inode as
 180                                     bad so it is no longer accessed, and then
 181                                     continue.
 182                           recover:  At present only supported is recovery of
 183                                     the boot sector from the backup copy.
 184                                     If read-only mount, the recovery is done
 185                                     in memory only and not written to disk.
 186                         Note that the options are additive, i.e. specifying:
 187                            errors=continue,errors=recover
 188                         means the driver will attempt to recover and if that
 189                         fails it will clean-up as much as possible and
 190                         continue.
 191
 192 mft_zone_multiplier=    Set the MFT zone multiplier for the volume (this
 193                         setting is not persistent across mounts and can be
 194                         changed from mount to mount but cannot be changed on
 195                         remount).  Values of 1 to 4 are allowed, 1 being the
 196                         default.  The MFT zone multiplier determines how much
 197                         space is reserved for the MFT on the volume.  If all
 198                         other space is used up, then the MFT zone will be
 199                         shrunk dynamically, so this has no impact on the
 200                         amount of free space.  However, it can have an impact
 201                         on performance by affecting fragmentation of the MFT.
 202                         In general use the default.  If you have a lot of small
 203                         files then use a higher value.  The values have the
 204                         following meaning:
 205                               Value          MFT zone size (% of volume size)
 206                                 1               12.5%
 207                                 2               25%
 208                                 3               37.5%
 209                                 4               50%
 210                         Note this option is irrelevant for read-only mounts.
 211
 212
 213 Known bugs and (mis-)features
 214 =============================
 215
 216 - The link count on each directory inode entry is set to 1, due to Linux not
 217   supporting directory hard links.  This may well confuse some user space
 218   applications, since the directory names will have the same inode numbers.
 219   This also speeds up ntfs_read_inode() immensely.  And we haven't found any
 220   problems with this approach so far.  If you find a problem with this, please
 221   let us know.
 222
 223
 224 Please send bug reports/comments/feedback/abuse to the Linux-NTFS development
 225 list at sourceforge: linux-ntfs-dev@lists.sourceforge.net
 226
 227
 228 Using NTFS volume and stripe sets
 229 =================================
 230
 231 For support of volume and stripe sets, you can either use the kernel's
 232 Device-Mapper driver or the kernel's Software RAID / MD driver.  The former is
 233 the recommended one to use for linear raid.  But the latter is required for
 234 raid level 5.  For striping and mirroring, either driver should work fine.
 235
 236
 237 The Device-Mapper driver
 238 ------------------------
 239
 240 You will need to create a table of the components of the volume/stripe set and
 241 how they fit together and load this into the kernel using the dmsetup utility
 242 (see man 8 dmsetup).
 243
 244 Linear volume sets, i.e. linear raid, has been tested and works fine.  Even
 245 though untested, there is no reason why stripe sets, i.e. raid level 0, and
 246 mirrors, i.e. raid level 1 should not work, too.  Stripes with parity, i.e.
 247 raid level 5, unfortunately cannot work yet because the current version of the
 248 Device-Mapper driver does not support raid level 5.  You may be able to use the
 249 Software RAID / MD driver for raid level 5, see the next section for details.
 250
 251 To create the table describing your volume you will need to know each of its
 252 components and their sizes in sectors, i.e. multiples of 512-byte blocks.
 253
 254 For NT4 fault tolerant volumes you can obtain the sizes using fdisk.  So for
 255 example if one of your partitions is /dev/hda2 you would do:
 256
 257 $ fdisk -ul /dev/hda
 258
 259 Disk /dev/hda: 81.9 GB, 81964302336 bytes
 260 255 heads, 63 sectors/track, 9964 cylinders, total 160086528 sectors
 261 Units = sectors of 1 * 512 = 512 bytes
 262
 263    Device Boot      Start         End      Blocks   Id  System
 264    /dev/hda1   *          63     4209029     2104483+  83  Linux
 265    /dev/hda2         4209030    37768814    16779892+  86  NTFS
 266    /dev/hda3        37768815    46170809     4200997+  83  Linux
 267
 268 And you would know that /dev/hda2 has a size of 37768814 - 4209030 + 1 =
 269 33559785 sectors.
 270
 271 For Win2k and later dynamic disks, you can for example use the ldminfo utility
 272 which is part of the Linux LDM tools (the latest version at the time of
 273 writing is linux-ldm-0.0.8.tar.bz2).  You can download it from:
 274         http://www.linux-ntfs.org/
 275 Simply extract the downloaded archive (tar xvjf linux-ldm-0.0.8.tar.bz2), go
 276 into it (cd linux-ldm-0.0.8) and change to the test directory (cd test).  You
 277 will find the precompiled (i386) ldminfo utility there.  NOTE: You will not be
 278 able to compile this yourself easily so use the binary version!
 279
 280 Then you would use ldminfo in dump mode to obtain the necessary information:
 281
 282 $ ./ldminfo --dump /dev/hda
 283
 284 This would dump the LDM database found on /dev/hda which describes all of your
 285 dynamic disks and all the volumes on them.  At the bottom you will see the
 286 VOLUME DEFINITIONS section which is all you really need.  You may need to look
 287 further above to determine which of the disks in the volume definitions is
 288 which device in Linux.  Hint: Run ldminfo on each of your dynamic disks and
 289 look at the Disk Id close to the top of the output for each (the PRIVATE HEADER
 290 section).  You can then find these Disk Ids in the VBLK DATABASE section in the
 291 <Disk> components where you will get the LDM Name for the disk that is found in
 292 the VOLUME DEFINITIONS section.
 293
 294 Note you will also need to enable the LDM driver in the Linux kernel.  If your
 295 distribution did not enable it, you will need to recompile the kernel with it
 296 enabled.  This will create the LDM partitions on each device at boot time.  You
 297 would then use those devices (for /dev/hda they would be /dev/hda1, 2, 3, etc)
 298 in the Device-Mapper table.
 299
 300 You can also bypass using the LDM driver by using the main device (e.g.
 301 /dev/hda) and then using the offsets of the LDM partitions into this device as
 302 the "Start sector of device" when creating the table.  Once again ldminfo would
 303 give you the correct information to do this.
 304
 305 Assuming you know all your devices and their sizes things are easy.
 306
 307 For a linear raid the table would look like this (note all values are in
 308 512-byte sectors):
 309
 310 --- cut here ---
 311 # Offset into   Size of this    Raid type       Device          Start sector
 312 # volume        device                                          of device
 313 0               1028161         linear          /dev/hda1       0
 314 1028161         3903762         linear          /dev/hdb2       0
 315 4931923         2103211         linear          /dev/hdc1       0
 316 --- cut here ---
 317
 318 For a striped volume, i.e. raid level 0, you will need to know the chunk size
 319 you used when creating the volume.  Windows uses 64kiB as the default, so it
 320 will probably be this unless you changes the defaults when creating the array.
 321
 322 For a raid level 0 the table would look like this (note all values are in
 323 512-byte sectors):
 324
 325 --- cut here ---
 326 # Offset   Size     Raid     Number   Chunk  1st        Start   2nd       Start
 327 # into     of the   type     of       size   Device     in      Device    in
 328 # volume   volume            stripes                    device            device
 329 0          2056320  striped  2        128    /dev/hda1  0       /dev/hdb1 0
 330 --- cut here ---
 331
 332 If there are more than two devices, just add each of them to the end of the
 333 line.
 334
 335 Finally, for a mirrored volume, i.e. raid level 1, the table would look like
 336 this (note all values are in 512-byte sectors):
 337
 338 --- cut here ---
 339 # Ofs Size   Raid   Log  Number Region Should Number Source  Start Target Start
 340 # in  of the type   type of log size   sync?  of     Device  in    Device in
 341 # vol volume             params              mirrors         Device       Device
 342 0    2056320 mirror core 2      16     nosync 2    /dev/hda1 0   /dev/hdb1 0
 343 --- cut here ---
 344
 345 If you are mirroring to multiple devices you can specify further targets at the
 346 end of the line.
 347
 348 Note the "Should sync?" parameter "nosync" means that the two mirrors are
 349 already in sync which will be the case on a clean shutdown of Windows.  If the
 350 mirrors are not clean, you can specify the "sync" option instead of "nosync"
 351 and the Device-Mapper driver will then copy the entirety of the "Source Device"
 352 to the "Target Device" or if you specified multiple target devices to all of
 353 them.
 354
 355 Once you have your table, save it in a file somewhere (e.g. /etc/ntfsvolume1),
 356 and hand it over to dmsetup to work with, like so:
 357
 358 $ dmsetup create myvolume1 /etc/ntfsvolume1
 359
 360 You can obviously replace "myvolume1" with whatever name you like.
 361
 362 If it all worked, you will now have the device /dev/device-mapper/myvolume1
 363 which you can then just use as an argument to the mount command as usual to
 364 mount the ntfs volume.  For example:
 365
 366 $ mount -t ntfs -o ro /dev/device-mapper/myvolume1 /mnt/myvol1
 367
 368 (You need to create the directory /mnt/myvol1 first and of course you can use
 369 anything you like instead of /mnt/myvol1 as long as it is an existing
 370 directory.)
 371
 372 It is advisable to do the mount read-only to see if the volume has been setup
 373 correctly to avoid the possibility of causing damage to the data on the ntfs
 374 volume.
 375
 376
 377 The Software RAID / MD driver
 378 -----------------------------
 379
 380 An alternative to using the Device-Mapper driver is to use the kernel's
 381 Software RAID / MD driver.  For which you need to set up your /etc/raidtab
 382 appropriately (see man 5 raidtab).
 383
 384 Linear volume sets, i.e. linear raid, as well as stripe sets, i.e. raid level
 385 0, have been tested and work fine (though see section "Limitations when using
 386 the MD driver with NTFS volumes" especially if you want to use linear raid).
 387 Even though untested, there is no reason why mirrors, i.e. raid level 1, and
 388 stripes with parity, i.e. raid level 5, should not work, too.
 389
 390 You have to use the "persistent-superblock 0" option for each raid-disk in the
 391 NTFS volume/stripe you are configuring in /etc/raidtab as the persistent
 392 superblock used by the MD driver would damage the NTFS volume.
 393
 394 Windows by default uses a stripe chunk size of 64k, so you probably want the
 395 "chunk-size 64k" option for each raid-disk, too.
 396
 397 For example, if you have a stripe set consisting of two partitions /dev/hda5
 398 and /dev/hdb1 your /etc/raidtab would look like this:
 399
 400 raiddev /dev/md0
 401         raid-level      0
 402         nr-raid-disks   2
 403         nr-spare-disks  0
 404         persistent-superblock   0
 405         chunk-size      64k
 406         device          /dev/hda5
 407         raid-disk       0
 408         device          /dev/hdb1
 409         raid-disk       1
 410
 411 For linear raid, just change the raid-level above to "raid-level linear", for
 412 mirrors, change it to "raid-level 1", and for stripe sets with parity, change
 413 it to "raid-level 5".
 414
 415 Note for stripe sets with parity you will also need to tell the MD driver
 416 which parity algorithm to use by specifying the option "parity-algorithm
 417 which", where you need to replace "which" with the name of the algorithm to
 418 use (see man 5 raidtab for available algorithms) and you will have to try the
 419 different available algorithms until you find one that works.  Make sure you
 420 are working read-only when playing with this as you may damage your data
 421 otherwise.  If you find which algorithm works please let us know (email the
 422 linux-ntfs developers list linux-ntfs-dev@lists.sourceforge.net or drop in on
 423 IRC in channel #ntfs on the irc.freenode.net network) so we can update this
 424 documentation.
 425
 426 Once the raidtab is setup, run for example raid0run -a to start all devices or
 427 raid0run /dev/md0 to start a particular md device, in this case /dev/md0.
 428
 429 Then just use the mount command as usual to mount the ntfs volume using for
 430 example:        mount -t ntfs -o ro /dev/md0 /mnt/myntfsvolume
 431
 432 It is advisable to do the mount read-only to see if the md volume has been
 433 setup correctly to avoid the possibility of causing damage to the data on the
 434 ntfs volume.
 435
 436
 437 Limitations when using the Software RAID / MD driver
 438 -----------------------------------------------------
 439
 440 Using the md driver will not work properly if any of your NTFS partitions have
 441 an odd number of sectors.  This is especially important for linear raid as all
 442 data after the first partition with an odd number of sectors will be offset by
 443 one or more sectors so if you mount such a partition with write support you
 444 will cause massive damage to the data on the volume which will only become
 445 apparent when you try to use the volume again under Windows.
 446
 447 So when using linear raid, make sure that all your partitions have an even
 448 number of sectors BEFORE attempting to use it.  You have been warned!
 449
 450 Even better is to simply use the Device-Mapper for linear raid and then you do
 451 not have this problem with odd numbers of sectors.