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