Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NTFS-3G(8)		    System Manager's Manual		    NTFS-3G(8)

       ntfs-3g - Third Generation Read/Write NTFS Driver

       ntfs-3g [-o option[,...]]  volume mount_point
       mount -t	ntfs-3g	[-o option[,...]]  volume mount_point
       lowntfs-3g [-o option[,...]]  volume mount_point
       mount -t	lowntfs-3g [-o option[,...]]  volume mount_point

       ntfs-3g	is  an	NTFS  driver,  which  can create, remove, rename, move
       files, directories, hard	links, and streams;  it	 can  read  and	 write
       files,  including  streams,  sparse  files and transparently compressed
       files; it can handle special files like symbolic	 links,	 devices,  and
       FIFOs;  moreover	 it provides standard management of file ownership and
       permissions, including POSIX ACLs.

       It comes	in two variants	ntfs-3g	and lowntfs-3g with a few  differences
       mentioned below in relevant options descriptions.

       The volume to be	mounted	can be either a	block device or	an image file.

   Access Handling and Security
       By  default,  files and directories are owned by	the effective user and
       group of	the mounting process, and everybody has	full read, write, exe-
       cution and directory browsing permissions.  You can also	assign permis-
       sions to	a single user by using the uid and/or the gid options together
       with the	umask, or fmask	and dmask options.

       Doing  so,  Windows  users  have	 full  access  to the files created by

       But, by setting the permissions option, you can benefit from  the  full
       ownership  and  permissions  features as	defined	by POSIX. Moreover, by
       defining	a Windows-to-Linux user	mapping, the  ownerships  and  permis-
       sions are even applied to Windows users and conversely.

       If  ntfs-3g is set setuid-root then non-root users will be also able to
       mount volumes.

   Windows Filename Compatibility
       NTFS supports several filename namespaces: DOS, Win32 and POSIX.	 While
       the  ntfs-3g driver handles all of them,	it always creates new files in
       the POSIX namespace for maximum portability and	interoperability  rea-
       sons.   This means that filenames are case sensitive and	all characters
       are allowed except '/' and '\0'.	This is	perfectly  legal  on  Windows,
       though  some application	may get	confused. The option windows_names may
       be used to apply	Windows	restrictions to	new file names.

   Alternate Data Streams (ADS)
       NTFS stores all data in streams.	Every file  has	 exactly  one  unnamed
       data  stream  and can have many named data streams.  The	size of	a file
       is the size of its unnamed data stream.	By default, ntfs-3g will  only
       read the	unnamed	data stream.

       By  using  the  options	"streams_interface=windows",  with the ntfs-3g
       driver (not possible with lowntfs-3g), you will be  able	 to  read  any
       named  data  streams,  simply  by  specifying the stream's name after a
       colon.  For example:

	      cat some.mp3:artist

       Named data streams act like normal files, so you	can  read  from	 them,
       write  to  them	and even delete	them (using rm).  You can list all the
       named data streams a file has by	getting	 the  "ntfs.streams.list"  ex-
       tended attribute.

       Below is	a summary of the options that ntfs-3g accepts.

       uid=value and gid=value
	      Set the owner and	the group of files and directories. The	values
	      are numerical.  The defaults are the uid and gid of the  current

	      Set  the	bitmask	of the file and	directory permissions that are
	      not present. The value is	given in octal.	The default value is 0
	      which means full access to everybody.

	      Set  the	 bitmask of the	file permissions that are not present.
	      The value	is given in octal. The default value is	0 which	 means
	      full access to everybody.

	      Set  the	 bitmask  of  the  directory  permissions that are not
	      present. The value is given in octal. The	 default  value	 is  0
	      which means full access to everybody.

	      Use  file	 file-name as the user mapping file instead of the de-
	      fault .NTFS-3G/UserMapping. If file-name defines	a  full	 path,
	      the  file	 must be located on a partition	previously mounted. If
	      it defines a relative path, it is	interpreted  relative  to  the
	      root of NTFS partition being mounted.

	      When  a  user  mapping  file is defined, the options uid=, gid=,
	      umask=, fmask=, dmask= and silent	are ignored.

	      Set standard permissions on created files	and use	 standard  ac-
	      cess control.  This option is set	by default when	a user mapping
	      file is present.

	      When creating a new file,	set its	initial	ownership and  protec-
	      tions  according	to  inheritance	rules defined in parent	direc-
	      tory. These rules	deviate	from Posix specifications, but yield a
	      better Windows compatibility.

       ro     Mount  filesystem	 read-only. Useful if Windows is hibernated or
	      the NTFS journal file is unclean.

	      This option can be useful	when wanting a language	 specific  lo-
	      cale  environment.   It  is  however  discouraged	as it leads to
	      files with untranslatable	chars to not be	visible.

       force  This option is obsolete. It has been superseded by  the  recover
	      and norecover options.

       ignore_case (only with lowntfs-3g)
	      Ignore character case when accessing a file (FOO,	Foo, foo, etc.
	      designate	the same file).	All files  are	displayed  with	 lower
	      case in directory	listings.

	      Unlike  in  case of read-only mount, the read-write mount	is de-
	      nied if the NTFS volume is hibernated. One needs either  to  re-
	      sume  Windows and	shutdown it properly, or use this option which
	      will remove the Windows  hibernation  file.  Please  note,  this
	      means  that  the	saved Windows session will be completely lost.
	      Use this option for your own responsibility.

       atime, noatime, relatime
	      The atime	option updates inode access time for each access.

	      The noatime option disables inode	access time updates which  can
	      speed  up	 file operations and prevent sleeping (notebook) disks
	      spinning up too often thus saving	energy and disk	lifetime.

	      The relatime option is very similar to noatime.  It updates  in-
	      ode  access times	relative to modify or change time.  The	access
	      time is only updated if the previous  access  time  was  earlier
	      than  the	current	modify or change time. Unlike noatime this op-
	      tion doesn't break applications that need	to know	if a file  has
	      been  read since the last	time it	was modified.  This is the de-
	      fault behaviour.

	      Show the metafiles in directory listings.	Otherwise the  default
	      behaviour	is to hide the metafiles, which	are special files used
	      to store the NTFS	structure. Please note that even when this op-
	      tion is specified, "$MFT"	may not	be visible due to a glibc bug.
	      Furthermore, irrespectively of show_sys_files, all files are ac-
	      cessible	by  name,  for	example	you can	always do "ls -l '$Up-

	      Hide the hidden files and	directories in directory listings, the
	      hidden files and directories being the ones whose	NTFS attribute
	      have the hidden flag set.	 The hidden files will not be selected
	      when  using wildcards in commands, but all files and directories
	      remain accessible	by full	name, for example you can always  dis-
	      play  the	 Windows  trash	 bin  directory	 by  : "ls -ld '$RECY-

	      Set the hidden flag in the NTFS attribute	for created files  and
	      directories  whose  first	 character  of the name	is a dot. Such
	      files and	directories normally do	not appear in directory	 list-
	      ings, and	when the flag is set they do not appear	in Windows di-
	      rectory displays either.

	      This option prevents files, directories and extended  attributes
	      to be created with a name	not allowed by windows,	either because
	      it contains some not allowed character (which are	the nine char-
	      acters " * / : < > ? \ | and those whose code is less than 0x20)
	      or because the last character is a space or a dot. Existing such
	      files can	still be read (and renamed).

	      This  option overrides the security measure restricting file ac-
	      cess to the user mounting	the filesystem.	This  option  is  only
	      allowed  to  root, but this restriction can be overridden	by the
	      'user_allow_other' option	in the /etc/fuse.conf file.

	      With this	option the maximum size	of read	operations can be set.
	      The default is infinite.	Note that the size of read requests is
	      limited anyway to	32 pages (which	is 128kbyte on i386).

       silent Do nothing, without returning any	error, on chmod	and chown  op-
	      erations,	 when  the  permissions	 option	is not set and no user
	      mapping file is defined. This option is on by default.

	      By default ntfs-3g acts as if "silent" (ignore errors  on	 chmod
	      and  chown),  "allow_other" (allow any user to access files) and
	      "nonempty" (allow	mounting on non-empty directories)  were  set,
	      and "no_def_opts"	cancels	these default options.

	      This  option  controls  how  the	user can access	Alternate Data
	      Streams (ADS) or in other	words, named data streams. It  can  be
	      set  to,	one of none, windows or	xattr. If the option is	set to
	      none, the	user will have no access to the	named data streams. If
	      it  is  set  to windows (not possible with lowntfs-3g), then the
	      user can access them just	like in	Windows	(eg. cat file:stream).
	      If  it's set to xattr, then the named data streams are mapped to
	      xattrs and user can manipulate them using	{get,set}fattr	utili-
	      ties. The	default	is xattr.

	      Same as streams_interface=xattr.

	      This  option should only be used in backup or restore situation.
	      It changes the apparent size of files and	the behavior  of  read
	      and write	operation so that encrypted files can be saved and re-
	      stored without being decrypted. The  user.ntfs.efsinfo  extended
	      attribute	 has  also to be saved and restored for	the file to be

	      This option enables creating new transparently compressed	 files
	      in directories marked for	compression. A directory is marked for
	      compression by setting the bit 11	(value 0x00000800) in its Win-
	      dows  attribute. In such a directory, new	files are created com-
	      pressed and new subdirectories are themselves  marked  for  com-
	      pression.	 The  option  and  the flag have no effect on existing

	      This option disables creating new	transparently compressed files
	      in directories marked for	compression. Existing compressed files
	      can still	be read	and updated. Currently this is the default op-

       debug  Makes ntfs-3g to print a lot of debug output from	libntfs-3g and

	      Makes ntfs-3g to not detach from terminal	and print  some	 debug

       NTFS  uses specific ids to record the ownership of files	instead	of the
       uid and gid used	by Linux. As a consequence a mapping between  the  ids
       has  to	be  defined for	ownerships to be recorded into NTFS and	recog-

       By default, this	mapping	is fetched from	the file  .NTFS-3G/UserMapping
       located	in  the	NTFS partition.	The option usermapping=	may be used to
       define another location.	When the option	permissions is set and no map-
       ping file is found, a default mapping is	used.

       Each  line  in the user mapping file defines a mapping. It is organized
       in three	fields separated by colons. The	first field identifies a  uid,
       the second field	identifies a gid and the third one identifies the cor-
       responding NTFS id, known as a SID. The uid and the  gid	 are  optional
       and defining both of them for the same SID is not recommended.

       If  no  interoperation  with  Windows is	needed,	you can	use the	option
       permissions to define a standard	mapping. Alternately, you  may	define
       your  own  mapping  by setting a	single default mapping with no uid and
       gid. In both cases, files created on Linux will appear  to  Windows  as
       owned  by  a  foreign user, and files created on	Windows	will appear to
       Linux as	owned by root. Just copy the example below and replace	the  9
       and 10-digit numbers by any number not greater than 4294967295. The re-
       sulting behavior	is the same as the one with the	option permission  set
       with no ownership option	and no user mapping file available.


       If  a  strong interoperation with Windows is needed, the	mapping	has to
       be defined for each user	and group known	in both	system,	and  the  SIDs
       used  by	 Windows has to	be collected. This will	lead to	a user mapping
       file like :


       The  utility  ntfs-3g.usermap may be used to create such	a user mapping

       Mount /dev/sda1 to /mnt/windows:

	      ntfs-3g /dev/sda1	/mnt/windows
	      mount -t ntfs-3g /dev/sda1 /mnt/windows

       Mount the ntfs data partition  /dev/sda3	 to  /mnt/data	with  standard
       Linux permissions applied :

	      ntfs-3g -o permissions /dev/sda3 /mnt/data
	      mount -t ntfs-3g -o permissions /dev/sda3	/mnt/data

       Read-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000
       to be the owner of all files:

	      ntfs-3g /dev/sda5	/home/user/mnt -o ro,uid=1000

       /etc/fstab entry	for the	above:
	      /dev/sda5	/home/user/mnt ntfs-3g ro,uid=1000 0 0

       Unmount /mnt/windows:

	      umount /mnt/windows

       To facilitate the use of	the ntfs-3g driver in scripts, an exit code is
       returned	 to give an indication of the mountability status of a volume.
       Value 0 means success, and all other ones mean an error.	The unique er-
       ror codes are documented	in the ntfs-3g.probe(8)	manual page.

       Please see

       for  common questions and known issues.	If you would find a new	one in
       the latest release of the software then please send an email describing
       it  in  detail. You can contact the development team on the ntfs-3g-de-	address.

       ntfs-3g was based on and	a major	improvement to ntfsmount  and  libntfs
       which  were  written by Yura Pakhuchiy and the Linux-NTFS team. The im-
       provements were made, the ntfs-3g project was initiated	and  currently
       led   by	 long  time  Linux-NTFS	 team  developer  Szabolcs  Szakacsits

       Several people made heroic efforts, often over five or more years which
       resulted	 the  ntfs-3g  driver.	Most  importantly they are Anton Alta-
       parmakov, Jean-Pierre AndrA(C), Richard	Russon,	 Szabolcs  Szakacsits,
       Yura Pakhuchiy, Yuval Fledel, and the author of the groundbreaking FUSE
       filesystem development framework, Miklos	Szeredi.

       ntfs-3g.probe(8), ntfsprogs(8), attr(5),	getfattr(1)

ntfs-3g	2010.10.2		 February 2010			    NTFS-3G(8)


Want to link to this manual page? Use this URL:

home | help