0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ================================
0004 The Linux NTFS filesystem driver
0005 ================================
0006
0007
0008 .. Table of contents
0009
0010 - Overview
0011 - Web site
0012 - Features
0013 - Supported mount options
0014 - Known bugs and (mis-)features
0015 - Using NTFS volume and stripe sets
0016 - The Device-Mapper driver
0017 - The Software RAID / MD driver
0018 - Limitations when using the MD driver
0019
0020
0021 Overview
0022 ========
0023
0024 Linux-NTFS comes with a number of user-space programs known as ntfsprogs.
0025 These include mkntfs, a full-featured ntfs filesystem format utility,
0026 ntfsundelete used for recovering files that were unintentionally deleted
0027 from an NTFS volume and ntfsresize which is used to resize an NTFS partition.
0028 See the web site for more information.
0029
0030 To mount an NTFS 1.2/3.x (Windows NT4/2000/XP/2003) volume, use the file
0031 system type 'ntfs'. The driver currently supports read-only mode (with no
0032 fault-tolerance, encryption or journalling) and very limited, but safe, write
0033 support.
0034
0035 For fault tolerance and raid support (i.e. volume and stripe sets), you can
0036 use the kernel's Software RAID / MD driver. See section "Using Software RAID
0037 with NTFS" for details.
0038
0039
0040 Web site
0041 ========
0042
0043 There is plenty of additional information on the linux-ntfs web site
0044 at http://www.linux-ntfs.org/
0045
0046 The web site has a lot of additional information, such as a comprehensive
0047 FAQ, documentation on the NTFS on-disk format, information on the Linux-NTFS
0048 userspace utilities, etc.
0049
0050
0051 Features
0052 ========
0053
0054 - This is a complete rewrite of the NTFS driver that used to be in the 2.4 and
0055 earlier kernels. This new driver implements NTFS read support and is
0056 functionally equivalent to the old ntfs driver and it also implements limited
0057 write support. The biggest limitation at present is that files/directories
0058 cannot be created or deleted. See below for the list of write features that
0059 are so far supported. Another limitation is that writing to compressed files
0060 is not implemented at all. Also, neither read nor write access to encrypted
0061 files is so far implemented.
0062 - The new driver has full support for sparse files on NTFS 3.x volumes which
0063 the old driver isn't happy with.
0064 - The new driver supports execution of binaries due to mmap() now being
0065 supported.
0066 - The new driver supports loopback mounting of files on NTFS which is used by
0067 some Linux distributions to enable the user to run Linux from an NTFS
0068 partition by creating a large file while in Windows and then loopback
0069 mounting the file while in Linux and creating a Linux filesystem on it that
0070 is used to install Linux on it.
0071 - A comparison of the two drivers using::
0072
0073 time find . -type f -exec md5sum "{}" \;
0074
0075 run three times in sequence with each driver (after a reboot) on a 1.4GiB
0076 NTFS partition, showed the new driver to be 20% faster in total time elapsed
0077 (from 9:43 minutes on average down to 7:53). The time spent in user space
0078 was unchanged but the time spent in the kernel was decreased by a factor of
0079 2.5 (from 85 CPU seconds down to 33).
0080 - The driver does not support short file names in general. For backwards
0081 compatibility, we implement access to files using their short file names if
0082 they exist. The driver will not create short file names however, and a
0083 rename will discard any existing short file name.
0084 - The new driver supports exporting of mounted NTFS volumes via NFS.
0085 - The new driver supports async io (aio).
0086 - The new driver supports fsync(2), fdatasync(2), and msync(2).
0087 - The new driver supports readv(2) and writev(2).
0088 - The new driver supports access time updates (including mtime and ctime).
0089 - The new driver supports truncate(2) and open(2) with O_TRUNC. But at present
0090 only very limited support for highly fragmented files, i.e. ones which have
0091 their data attribute split across multiple extents, is included. Another
0092 limitation is that at present truncate(2) will never create sparse files,
0093 since to mark a file sparse we need to modify the directory entry for the
0094 file and we do not implement directory modifications yet.
0095 - The new driver supports write(2) which can both overwrite existing data and
0096 extend the file size so that you can write beyond the existing data. Also,
0097 writing into sparse regions is supported and the holes are filled in with
0098 clusters. But at present only limited support for highly fragmented files,
0099 i.e. ones which have their data attribute split across multiple extents, is
0100 included. Another limitation is that write(2) will never create sparse
0101 files, since to mark a file sparse we need to modify the directory entry for
0102 the file and we do not implement directory modifications yet.
0103
0104 Supported mount options
0105 =======================
0106
0107 In addition to the generic mount options described by the manual page for the
0108 mount command (man 8 mount, also see man 5 fstab), the NTFS driver supports the
0109 following mount options:
0110
0111 ======================= =======================================================
0112 iocharset=name Deprecated option. Still supported but please use
0113 nls=name in the future. See description for nls=name.
0114
0115 nls=name Character set to use when returning file names.
0116 Unlike VFAT, NTFS suppresses names that contain
0117 unconvertible characters. Note that most character
0118 sets contain insufficient characters to represent all
0119 possible Unicode characters that can exist on NTFS.
0120 To be sure you are not missing any files, you are
0121 advised to use nls=utf8 which is capable of
0122 representing all Unicode characters.
0123
0124 utf8=<bool> Option no longer supported. Currently mapped to
0125 nls=utf8 but please use nls=utf8 in the future and
0126 make sure utf8 is compiled either as module or into
0127 the kernel. See description for nls=name.
0128
0129 uid=
0130 gid=
0131 umask= Provide default owner, group, and access mode mask.
0132 These options work as documented in mount(8). By
0133 default, the files/directories are owned by root and
0134 he/she has read and write permissions, as well as
0135 browse permission for directories. No one else has any
0136 access permissions. I.e. the mode on all files is by
0137 default rw------- and for directories rwx------, a
0138 consequence of the default fmask=0177 and dmask=0077.
0139 Using a umask of zero will grant all permissions to
0140 everyone, i.e. all files and directories will have mode
0141 rwxrwxrwx.
0142
0143 fmask=
0144 dmask= Instead of specifying umask which applies both to
0145 files and directories, fmask applies only to files and
0146 dmask only to directories.
0147
0148 sloppy=<BOOL> If sloppy is specified, ignore unknown mount options.
0149 Otherwise the default behaviour is to abort mount if
0150 any unknown options are found.
0151
0152 show_sys_files=<BOOL> If show_sys_files is specified, show the system files
0153 in directory listings. Otherwise the default behaviour
0154 is to hide the system files.
0155 Note that even when show_sys_files is specified, "$MFT"
0156 will not be visible due to bugs/mis-features in glibc.
0157 Further, note that irrespective of show_sys_files, all
0158 files are accessible by name, i.e. you can always do
0159 "ls -l \$UpCase" for example to specifically show the
0160 system file containing the Unicode upcase table.
0161
0162 case_sensitive=<BOOL> If case_sensitive is specified, treat all file names as
0163 case sensitive and create file names in the POSIX
0164 namespace. Otherwise the default behaviour is to treat
0165 file names as case insensitive and to create file names
0166 in the WIN32/LONG name space. Note, the Linux NTFS
0167 driver will never create short file names and will
0168 remove them on rename/delete of the corresponding long
0169 file name.
0170 Note that files remain accessible via their short file
0171 name, if it exists. If case_sensitive, you will need
0172 to provide the correct case of the short file name.
0173
0174 disable_sparse=<BOOL> If disable_sparse is specified, creation of sparse
0175 regions, i.e. holes, inside files is disabled for the
0176 volume (for the duration of this mount only). By
0177 default, creation of sparse regions is enabled, which
0178 is consistent with the behaviour of traditional Unix
0179 filesystems.
0180
0181 errors=opt What to do when critical filesystem errors are found.
0182 Following values can be used for "opt":
0183
0184 ======== =========================================
0185 continue DEFAULT, try to clean-up as much as
0186 possible, e.g. marking a corrupt inode as
0187 bad so it is no longer accessed, and then
0188 continue.
0189 recover At present only supported is recovery of
0190 the boot sector from the backup copy.
0191 If read-only mount, the recovery is done
0192 in memory only and not written to disk.
0193 ======== =========================================
0194
0195 Note that the options are additive, i.e. specifying::
0196
0197 errors=continue,errors=recover
0198
0199 means the driver will attempt to recover and if that
0200 fails it will clean-up as much as possible and
0201 continue.
0202
0203 mft_zone_multiplier= Set the MFT zone multiplier for the volume (this
0204 setting is not persistent across mounts and can be
0205 changed from mount to mount but cannot be changed on
0206 remount). Values of 1 to 4 are allowed, 1 being the
0207 default. The MFT zone multiplier determines how much
0208 space is reserved for the MFT on the volume. If all
0209 other space is used up, then the MFT zone will be
0210 shrunk dynamically, so this has no impact on the
0211 amount of free space. However, it can have an impact
0212 on performance by affecting fragmentation of the MFT.
0213 In general use the default. If you have a lot of small
0214 files then use a higher value. The values have the
0215 following meaning:
0216
0217 ===== =================================
0218 Value MFT zone size (% of volume size)
0219 ===== =================================
0220 1 12.5%
0221 2 25%
0222 3 37.5%
0223 4 50%
0224 ===== =================================
0225
0226 Note this option is irrelevant for read-only mounts.
0227 ======================= =======================================================
0228
0229
0230 Known bugs and (mis-)features
0231 =============================
0232
0233 - The link count on each directory inode entry is set to 1, due to Linux not
0234 supporting directory hard links. This may well confuse some user space
0235 applications, since the directory names will have the same inode numbers.
0236 This also speeds up ntfs_read_inode() immensely. And we haven't found any
0237 problems with this approach so far. If you find a problem with this, please
0238 let us know.
0239
0240
0241 Please send bug reports/comments/feedback/abuse to the Linux-NTFS development
0242 list at sourceforge: linux-ntfs-dev@lists.sourceforge.net
0243
0244
0245 Using NTFS volume and stripe sets
0246 =================================
0247
0248 For support of volume and stripe sets, you can either use the kernel's
0249 Device-Mapper driver or the kernel's Software RAID / MD driver. The former is
0250 the recommended one to use for linear raid. But the latter is required for
0251 raid level 5. For striping and mirroring, either driver should work fine.
0252
0253
0254 The Device-Mapper driver
0255 ------------------------
0256
0257 You will need to create a table of the components of the volume/stripe set and
0258 how they fit together and load this into the kernel using the dmsetup utility
0259 (see man 8 dmsetup).
0260
0261 Linear volume sets, i.e. linear raid, has been tested and works fine. Even
0262 though untested, there is no reason why stripe sets, i.e. raid level 0, and
0263 mirrors, i.e. raid level 1 should not work, too. Stripes with parity, i.e.
0264 raid level 5, unfortunately cannot work yet because the current version of the
0265 Device-Mapper driver does not support raid level 5. You may be able to use the
0266 Software RAID / MD driver for raid level 5, see the next section for details.
0267
0268 To create the table describing your volume you will need to know each of its
0269 components and their sizes in sectors, i.e. multiples of 512-byte blocks.
0270
0271 For NT4 fault tolerant volumes you can obtain the sizes using fdisk. So for
0272 example if one of your partitions is /dev/hda2 you would do::
0273
0274 $ fdisk -ul /dev/hda
0275
0276 Disk /dev/hda: 81.9 GB, 81964302336 bytes
0277 255 heads, 63 sectors/track, 9964 cylinders, total 160086528 sectors
0278 Units = sectors of 1 * 512 = 512 bytes
0279
0280 Device Boot Start End Blocks Id System
0281 /dev/hda1 * 63 4209029 2104483+ 83 Linux
0282 /dev/hda2 4209030 37768814 16779892+ 86 NTFS
0283 /dev/hda3 37768815 46170809 4200997+ 83 Linux
0284
0285 And you would know that /dev/hda2 has a size of 37768814 - 4209030 + 1 =
0286 33559785 sectors.
0287
0288 For Win2k and later dynamic disks, you can for example use the ldminfo utility
0289 which is part of the Linux LDM tools (the latest version at the time of
0290 writing is linux-ldm-0.0.8.tar.bz2). You can download it from:
0291
0292 http://www.linux-ntfs.org/
0293
0294 Simply extract the downloaded archive (tar xvjf linux-ldm-0.0.8.tar.bz2), go
0295 into it (cd linux-ldm-0.0.8) and change to the test directory (cd test). You
0296 will find the precompiled (i386) ldminfo utility there. NOTE: You will not be
0297 able to compile this yourself easily so use the binary version!
0298
0299 Then you would use ldminfo in dump mode to obtain the necessary information::
0300
0301 $ ./ldminfo --dump /dev/hda
0302
0303 This would dump the LDM database found on /dev/hda which describes all of your
0304 dynamic disks and all the volumes on them. At the bottom you will see the
0305 VOLUME DEFINITIONS section which is all you really need. You may need to look
0306 further above to determine which of the disks in the volume definitions is
0307 which device in Linux. Hint: Run ldminfo on each of your dynamic disks and
0308 look at the Disk Id close to the top of the output for each (the PRIVATE HEADER
0309 section). You can then find these Disk Ids in the VBLK DATABASE section in the
0310 <Disk> components where you will get the LDM Name for the disk that is found in
0311 the VOLUME DEFINITIONS section.
0312
0313 Note you will also need to enable the LDM driver in the Linux kernel. If your
0314 distribution did not enable it, you will need to recompile the kernel with it
0315 enabled. This will create the LDM partitions on each device at boot time. You
0316 would then use those devices (for /dev/hda they would be /dev/hda1, 2, 3, etc)
0317 in the Device-Mapper table.
0318
0319 You can also bypass using the LDM driver by using the main device (e.g.
0320 /dev/hda) and then using the offsets of the LDM partitions into this device as
0321 the "Start sector of device" when creating the table. Once again ldminfo would
0322 give you the correct information to do this.
0323
0324 Assuming you know all your devices and their sizes things are easy.
0325
0326 For a linear raid the table would look like this (note all values are in
0327 512-byte sectors)::
0328
0329 # Offset into Size of this Raid type Device Start sector
0330 # volume device of device
0331 0 1028161 linear /dev/hda1 0
0332 1028161 3903762 linear /dev/hdb2 0
0333 4931923 2103211 linear /dev/hdc1 0
0334
0335 For a striped volume, i.e. raid level 0, you will need to know the chunk size
0336 you used when creating the volume. Windows uses 64kiB as the default, so it
0337 will probably be this unless you changes the defaults when creating the array.
0338
0339 For a raid level 0 the table would look like this (note all values are in
0340 512-byte sectors)::
0341
0342 # Offset Size Raid Number Chunk 1st Start 2nd Start
0343 # into of the type of size Device in Device in
0344 # volume volume stripes device device
0345 0 2056320 striped 2 128 /dev/hda1 0 /dev/hdb1 0
0346
0347 If there are more than two devices, just add each of them to the end of the
0348 line.
0349
0350 Finally, for a mirrored volume, i.e. raid level 1, the table would look like
0351 this (note all values are in 512-byte sectors)::
0352
0353 # Ofs Size Raid Log Number Region Should Number Source Start Target Start
0354 # in of the type type of log size sync? of Device in Device in
0355 # vol volume params mirrors Device Device
0356 0 2056320 mirror core 2 16 nosync 2 /dev/hda1 0 /dev/hdb1 0
0357
0358 If you are mirroring to multiple devices you can specify further targets at the
0359 end of the line.
0360
0361 Note the "Should sync?" parameter "nosync" means that the two mirrors are
0362 already in sync which will be the case on a clean shutdown of Windows. If the
0363 mirrors are not clean, you can specify the "sync" option instead of "nosync"
0364 and the Device-Mapper driver will then copy the entirety of the "Source Device"
0365 to the "Target Device" or if you specified multiple target devices to all of
0366 them.
0367
0368 Once you have your table, save it in a file somewhere (e.g. /etc/ntfsvolume1),
0369 and hand it over to dmsetup to work with, like so::
0370
0371 $ dmsetup create myvolume1 /etc/ntfsvolume1
0372
0373 You can obviously replace "myvolume1" with whatever name you like.
0374
0375 If it all worked, you will now have the device /dev/device-mapper/myvolume1
0376 which you can then just use as an argument to the mount command as usual to
0377 mount the ntfs volume. For example::
0378
0379 $ mount -t ntfs -o ro /dev/device-mapper/myvolume1 /mnt/myvol1
0380
0381 (You need to create the directory /mnt/myvol1 first and of course you can use
0382 anything you like instead of /mnt/myvol1 as long as it is an existing
0383 directory.)
0384
0385 It is advisable to do the mount read-only to see if the volume has been setup
0386 correctly to avoid the possibility of causing damage to the data on the ntfs
0387 volume.
0388
0389
0390 The Software RAID / MD driver
0391 -----------------------------
0392
0393 An alternative to using the Device-Mapper driver is to use the kernel's
0394 Software RAID / MD driver. For which you need to set up your /etc/raidtab
0395 appropriately (see man 5 raidtab).
0396
0397 Linear volume sets, i.e. linear raid, as well as stripe sets, i.e. raid level
0398 0, have been tested and work fine (though see section "Limitations when using
0399 the MD driver with NTFS volumes" especially if you want to use linear raid).
0400 Even though untested, there is no reason why mirrors, i.e. raid level 1, and
0401 stripes with parity, i.e. raid level 5, should not work, too.
0402
0403 You have to use the "persistent-superblock 0" option for each raid-disk in the
0404 NTFS volume/stripe you are configuring in /etc/raidtab as the persistent
0405 superblock used by the MD driver would damage the NTFS volume.
0406
0407 Windows by default uses a stripe chunk size of 64k, so you probably want the
0408 "chunk-size 64k" option for each raid-disk, too.
0409
0410 For example, if you have a stripe set consisting of two partitions /dev/hda5
0411 and /dev/hdb1 your /etc/raidtab would look like this::
0412
0413 raiddev /dev/md0
0414 raid-level 0
0415 nr-raid-disks 2
0416 nr-spare-disks 0
0417 persistent-superblock 0
0418 chunk-size 64k
0419 device /dev/hda5
0420 raid-disk 0
0421 device /dev/hdb1
0422 raid-disk 1
0423
0424 For linear raid, just change the raid-level above to "raid-level linear", for
0425 mirrors, change it to "raid-level 1", and for stripe sets with parity, change
0426 it to "raid-level 5".
0427
0428 Note for stripe sets with parity you will also need to tell the MD driver
0429 which parity algorithm to use by specifying the option "parity-algorithm
0430 which", where you need to replace "which" with the name of the algorithm to
0431 use (see man 5 raidtab for available algorithms) and you will have to try the
0432 different available algorithms until you find one that works. Make sure you
0433 are working read-only when playing with this as you may damage your data
0434 otherwise. If you find which algorithm works please let us know (email the
0435 linux-ntfs developers list linux-ntfs-dev@lists.sourceforge.net or drop in on
0436 IRC in channel #ntfs on the irc.freenode.net network) so we can update this
0437 documentation.
0438
0439 Once the raidtab is setup, run for example raid0run -a to start all devices or
0440 raid0run /dev/md0 to start a particular md device, in this case /dev/md0.
0441
0442 Then just use the mount command as usual to mount the ntfs volume using for
0443 example::
0444
0445 mount -t ntfs -o ro /dev/md0 /mnt/myntfsvolume
0446
0447 It is advisable to do the mount read-only to see if the md volume has been
0448 setup correctly to avoid the possibility of causing damage to the data on the
0449 ntfs volume.
0450
0451
0452 Limitations when using the Software RAID / MD driver
0453 -----------------------------------------------------
0454
0455 Using the md driver will not work properly if any of your NTFS partitions have
0456 an odd number of sectors. This is especially important for linear raid as all
0457 data after the first partition with an odd number of sectors will be offset by
0458 one or more sectors so if you mount such a partition with write support you
0459 will cause massive damage to the data on the volume which will only become
0460 apparent when you try to use the volume again under Windows.
0461
0462 So when using linear raid, make sure that all your partitions have an even
0463 number of sectors BEFORE attempting to use it. You have been warned!
0464
0465 Even better is to simply use the Device-Mapper for linear raid and then you do
0466 not have this problem with odd numbers of sectors.
