The Linux NTFS filesystem driver
================================


Table of contents
=================

- Overview
- Supported mount options
- Features
- Known bugs and (mis-)features
- Using Software RAID with NTFS
- Limitiations when using the MD driver
- ChangeLog


Overview
========

To mount an NTFS 1.2/3.x (Windows NT4/2000/XP) volume, use the filesystem
type 'ntfs'. The driver currently works only in read-only mode, with no
fault-tolerance or journalling supported.

For fault tolerance and raid support (i.e. volume and stripe sets), you can use
the kernel's Software RAID / MD driver. See section "Using Software RAID with
NTFS" for details.


Supported mount options
=======================

In addition to the generic mount options described by the manual page for the
mount command (man 8 mount, also see man 5 fstab), the NTFS driver supports the
following mount options:

iocharset=name		Deprecated option. Still supported but please use
			nls=name in the future. See description for nls=name.

nls=name		Character set to use when returning file names.
			Unlike VFAT, NTFS suppresses names that contain
			unconvertible characters. Note that most character
			sets contain insufficient characters to represent all
			possible Unicode characters that can exist on NTFS. To
			be sure you are not missing any files, you are advised
			to use nls=utf8 which is capable of representing all
			Unicode characters.

utf8=<bool>		Option no longer supported. Currently mapped to
			nls=utf8 but please use nls=utf8 in the future and
			make sure utf8 is compiled either as module or into
			the kernel. See description for nls=name.

uid=
gid=
umask=			Provide default owner, group, and access mode mask.
			These options work as documented in mount(8). By
			default, the files/directories are owned by root and
			he/she has read and write permissions, as well as
			browse permission for directories. No one else has any
			access permissions. I.e. the mode on all files is by
			default rw------- and for directories rwx------, a
			consequence of the default fmask=0177 and dmask=0077.
			Using a umask of zero will grant all permissions to
			everyone, i.e. all files and directories will have mode
			rwxrwxrwx.

fmask=
dmask=			Instead of specifying umask which applies both to
			files and directories, fmask applies only to files and
			dmask only to directories.

sloppy=<BOOL>		If sloppy is specified, ignore unknown mount options.
			Otherwise the default behaviour is to abort mount if
			any unknown options are found.

posix=<bool>		Deprecated option. Still supported but please use
			show_inodes=posix in the future. See description for
			show_inodes=opt.

show_sys_files=<bool>	Deprecated option. Still supported but please use
			show_inodes=system in the future. See description for
			show_inodes=opt.

show_inodes=opt		Allows choice of which types of inode names readdir()
			returns, i.e. this affects what "ls" shows. Following
			values can be used for "opt":
			   system: show system files
			   win32:  long file names (includes POSIX) [DEFAULT]
			   long:   same as win32
			   dos:    short file names only (excludes POSIX)
			   short:  same as dos
			   posix:  same as both win32 and dos
			   all:    all file names
			Note that the options are additive, i.e. specifying:
			   show_inodes=system,show_inodes=win32,show_inodes=dos
			is the same as specifying:
			   show_inodes=all
			Note that the "posix" and "all" options will show all
			directory names, BUT the link count on each directory
			inode entry is set to 1, due to Linux not supporting
			directory hard links. This may well confuse some
			user space applications, since the directory names will
			have the same inode numbers. Thus it is NOT advisable
			to use the "posix" and "all" options. We provide them
			only for completeness sake.
			Further, note that the "system" option will not show
			"$MFT" due to bugs/mis-features in glibc. Even though
			it does not show, you can specifically "ls" it:
				ls -l \$MFT
			And of course you can stat it, too.
			Further, note that irrespective of what show_inodes
			option(s) you use, all files are accessible when you
			specify the correct name, even though they may not be
			shown in a normal "ls", i.e. you can always access the
			system files and both the short and long file names of
			files and directories.
			Finally, note that win32 and dos file names are not
			case sensitive and can be accessed using any
			combination of lower and upper case, while POSIX file
			names are case sensitive and they can only be accessed
			given the correct case.

errors=opt		What to do when critical file system errors are found.
			Following values can be used for "opt":
			  continue: DEFAULT, try to clean-up as much as
				    possible, e.g. marking a corrupt inode as
				    bad so it is no longer accessed, and then
				    continue.
			  recover:  At present only supported is recovery of
				    the boot sector from the backup copy. If a
				    read-only mount, the recovery is done in
				    memory only and not written to disk.
			Note that the options are additive, i.e. specifying:
			   errors=continue,errors=recover
			This means the driver will attempt to recover and if
			that fails it will clean-up as much as possible and
			continue.

mft_zone_multiplier=	Set the MFT zone multiplier for the volume (this
			setting is not persistent across mounts and can be
			changed from mount to mount but cannot be changed on
			remount). Values of 1 to 4 are allowed, 1 being the
			default. The MFT zone multiplier determines how much
			space is reserved for the MFT on the volume. If all
			other space is used up, then the MFT zone will be
			shrunk dynamically, so this has no impact on the
			amount of free space. However, it can have an impact
			on performance by affecting fragmentation of the MFT.
			In general use the default. If you have a lot of small
			files then use a higher value. The values have the
			following meaning:
			      Value	     MFT zone size (% of volume size)
				1		12.5%
				2		25%
				3		37.5%
				4		50%
			Note this option is irrelevant for read-only mounts.


Features
========

- This is a complete rewrite of the NTFS driver that used to be in the kernel.
  This new driver implements NTFS read support and is functionally equivalent
  to the old ntfs driver.
- The new driver has full support for sparse files on NTFS 3.x volumes which
  the old driver isn't happy with.
- The new driver supports execution of binaries due to mmap() now being
  supported.
- A comparison of the two drivers using:
	time find . -type f -exec md5sum "{}" \;
  run three times in sequence with each driver (after a reboot) on a 1.4GiB
  NTFS partition, showed the new driver to be 20% faster in total time elapsed
  (from 9:43 minutes on average down to 7:53). The time spent in user space
  was unchanged but the time spent in the kernel was decreased by a factor of
  2.5 (from 85 CPU seconds down to 33).


Known bugs and (mis-)features
=============================

- None

Please send bug reports/comments/feedback/abuse to the Linux-NTFS development
list at sourceforge: linux-ntfs-dev@lists.sourceforge.net


Using Software RAID with NTFS
=============================

For support of volume and stripe sets, use the kernel's Software RAID / MD
driver and set up your /etc/raidtab appropriately (see man 5 raidtab).

Linear volume sets, i.e. linear raid, as well as stripe sets, i.e. raid level 0,
have been tested and work fine (though see section "Limitiations when using the
MD driver with NTFS volumes" especially if you want to use linear raid). Even
though untested, there is no reason why mirrors, i.e. raid level 1, and stripes
with parity, i.e. raid level 5, should not work, too.

You have to use the "persistent-superblock 0" option for each raid-disk in the
NTFS volume/stripe you are configuring in /etc/raidtab as the persistent
superblock used by the MD driver would damange the NTFS volume.

Windows by default uses a stripe chunk size of 64k, so you probably want the
"chunk-size 64k" option for each raid-disk, too.

For example, if you have a stripe set consisting of two partitions /dev/hda5
and /dev/hdb1 your /etc/raidtab would look like this:

raiddev /dev/md0
	raid-level	0
	nr-raid-disks	2
	nr-spare-disks	0
	persistent-superblock	0
	chunk-size	64k
	device		/dev/hda5
	raid-disk	0
	device		/dev/hdb1
	raid-disl	1

For linear raid, just change the raid-level above to "raid-level linear", for
mirrors, change it to "raid-level 1", and for stripe sets with parity, change
it to "raid-level 5".

Note for stripe sets with parity you will also need to tell the MD driver which
parity algorithm to use by specifying the option "parity-algorithm which",
where you need to replace "which" with the name of the algorithm to use (see
man 5 raidtab for available algorithms) and you will have to try the different
available algorithms until you find one that works. Make sure you are working
read-only when playing with this as you may damage your data otherwise. If you
find which algorithm works please let us know (email the linux-ntfs developers
list linux-ntfs-dev@lists.sourceforge.net or drop in on IRC in channel #ntfs
on the irc.openprojects.net network) so we can update this documentation.

Once the raidtab is setup, run for example raid0run -a to start all devices or
raid0run /dev/md0 to start a particular md device, in this case /dev/md0.

Then just use the mount command as usual to mount the ntfs volume using for
example:	mount -t ntfs -o ro /dev/md0 /mnt/myntfsvolume

It is advisable to do the mount read-only to see if the md volume has been
setup correctly to avoid the possibility of causing damage to the data on the
ntfs volume.


Limitiations when using the MD driver
=====================================

Using the md driver will not work properly if any of your NTFS partitions have
an odd number of sectors. This is especially important for linear raid as all
data after the first partition with an odd number of sectors will be offset by
one or more sectors so if you mount such a partition with write support you
will cause massive damage to the data on the volume which will only become
apparent when you try to use the volume again under Windows.

So when using linear raid, make sure that all your partitions have an even
number of sectors BEFORE attempting to use it. You have been warned!


ChangeLog
=========

Note that a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog.

2.0.6:
	- Major bugfix to make compatible with other kernel changes. This fixes
	  the hangs/oopses on umount.
	- Locking cleanup in directory operations (remove BKL usage).
2.0.5:
	- Major buffer overflow bug fix.
	- Minor cleanups and updates for kernel 2.5.12.
2.0.4:
	- Cleanups and updates for kernel 2.5.11.
2.0.3:
	- Small bug fixes, cleanups, and performance improvements.
2.0.2:
	- Use default fmask of 0177 so that files are no executable by default.
	  If you want owner executable files, just use fmask=0077.
	- Update for kernel 2.5.9 but preserve backwards compatibility with
	  kernel 2.5.7.
	- Minor bug fixes, cleanups, and updates.
2.0.1:
	- Minor updates, primarily set the executable bit by default on files
	  so they can be executed.
2.0.0:
	- Started ChangeLog.

