1NTFS-3G(8)                  System Manager's Manual                 NTFS-3G(8)
2
3
4

NAME

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

SYNOPSIS

9       ntfs-3g [-o option[,...]]  volume mount_point
10       mount -t ntfs-3g [-o option[,...]]  volume mount_point
11       lowntfs-3g [-o option[,...]]  volume mount_point
12       mount -t lowntfs-3g [-o option[,...]]  volume mount_point
13

DESCRIPTION

15       ntfs-3g  is  an  NTFS  driver,  which  can create, remove, rename, move
16       files, directories, hard links, and streams;  it  can  read  and  write
17       files,  including  streams,  sparse  files and transparently compressed
18       files; it can handle special files like symbolic  links,  devices,  and
19       FIFOs;  moreover  it provides standard management of file ownership and
20       permissions, including POSIX ACLs.
21
22       It comes in two variants ntfs-3g and lowntfs-3g with a few  differences
23       mentioned below in relevant options descriptions.
24
25       The volume to be mounted can be either a block device or an image file.
26
27   Windows hibernation and fast restarting
28       On  computers  which  can be dual-booted into Windows or Linux, Windows
29       has to be fully shut down before booting into Linux, otherwise the NTFS
30       file systems on internal disks may be left in an inconsistent state and
31       changes made by Linux may be ignored by Windows.
32
33       So, Windows may not be left in  hibernation  when  starting  Linux,  in
34       order  to  avoid  inconsistencies.  Moreover,  the fast restart feature
35       available on recent Windows systems has to be  disabled.  This  can  be
36       achieved  by issuing as an Administrator the Windows command which dis‐
37       ables both hibernation and fast restarting :
38
39              powercfg /h off
40
41
42   Access Handling and Security
43       By default, files and directories are owned by the effective  user  and
44       group of the mounting process, and everybody has full read, write, exe‐
45       cution and directory browsing permissions.  You can also assign permis‐
46       sions to a single user by using the uid and/or the gid options together
47       with the umask, or fmask and dmask options.
48
49       Doing so, Windows users have  full  access  to  the  files  created  by
50       ntfs-3g.
51
52       But,  by  setting the permissions option, you can benefit from the full
53       ownership and permissions features as defined by  POSIX.  Moreover,  by
54       defining  a  Windows-to-Linux  user mapping, the ownerships and permis‐
55       sions are even applied to Windows users and conversely.
56
57       If ntfs-3g is set setuid-root then non-root users will be also able  to
58       mount volumes.
59
60   Windows Filename Compatibility
61       NTFS  supports several filename namespaces: DOS, Win32 and POSIX. While
62       the ntfs-3g driver handles all of them, it always creates new files  in
63       the  POSIX  namespace for maximum portability and interoperability rea‐
64       sons.  This means that filenames are case sensitive and all  characters
65       are  allowed  except  '/' and '\0'. This is perfectly legal on Windows,
66       though some application may get confused. The option windows_names  may
67       be used to apply Windows restrictions to new file names.
68
69   Alternate Data Streams (ADS)
70       NTFS  stores  all  data  in streams. Every file has exactly one unnamed
71       data stream and can have many named data streams.  The size of  a  file
72       is  the size of its unnamed data stream.  By default, ntfs-3g will only
73       read the unnamed data stream.
74
75       By using the  options  "streams_interface=windows",  with  the  ntfs-3g
76       driver  (not  possible  with  lowntfs-3g), you will be able to read any
77       named data streams, simply by specifying  the  stream's  name  after  a
78       colon.  For example:
79
80              cat some.mp3:artist
81
82       Named  data  streams  act like normal files, so you can read from them,
83       write to them and even delete them (using rm).  You can  list  all  the
84       named  data  streams  a  file  has  by  getting the "ntfs.streams.list"
85       extended attribute.
86

OPTIONS

88       Below is a summary of the options that ntfs-3g accepts.
89
90       uid=value and gid=value
91              Set the owner and the group of files and directories. The values
92              are  numerical.  The defaults are the uid and gid of the current
93              process.
94
95       umask=value
96              Set the  bitmask of the file and directory permissions that  are
97              not present. The value is given in octal. The default value is 0
98              which means full access to everybody.
99
100       fmask=value
101              Set the  bitmask of the file permissions that are  not  present.
102              The  value is given in octal. The default value is 0 which means
103              full access to everybody.
104
105       dmask=value
106              Set the  bitmask of  the  directory  permissions  that  are  not
107              present.  The  value  is  given in octal. The default value is 0
108              which means full access to everybody.
109
110       usermapping=file-name
111              Use file file-name as the  user  mapping  file  instead  of  the
112              default  .NTFS-3G/UserMapping. If file-name defines a full path,
113              the file must be located on a partition previously  mounted.  If
114              it  defines  a  relative path, it is interpreted relative to the
115              root of NTFS partition being mounted.
116
117              When a user mapping file is defined,  the  options  uid=,  gid=,
118              umask=, fmask=, dmask= and silent are ignored.
119
120       permissions
121              Set  standard  permissions  on  created  files  and use standard
122              access control.  This option is set by default when a user  map‐
123              ping file is present.
124
125       acl    Enable  setting  Posix  ACLs  on  created files and use them for
126              access control.  This  option  is  only  available  on  specific
127              builds. It is set by default when a user mapping file is present
128              and the permissions mount option is not set.
129
130       inherit
131              When creating a new file, set its initial protections  according
132              to  inheritance  rules  defined in parent directory. These rules
133              deviate from Posix specifications, but yield  a  better  Windows
134              compatibility.  The  permissions  option or a valid user mapping
135              file is required for this option to be effective.
136
137       ro     Mount filesystem read-only. Useful if Windows is  hibernated  or
138              the NTFS journal file is unclean.
139
140       locale=value
141              This  option  can  be  useful  when  wanting a language specific
142              locale environment.  It is however discouraged as  it  leads  to
143              files with untranslatable chars to not be visible.
144
145       force  This  option  is obsolete. It has been superseded by the recover
146              and norecover options.
147
148       recover
149              Recover and try to mount a partition  which  was  not  unmounted
150              properly  by  Windows. The Windows logfile is cleared, which may
151              cause inconsistencies.  Currently this is the default option.
152
153       norecover
154              Do not try to mount a partition which was not unmounted properly
155              by Windows.
156
157       ignore_case (only with lowntfs-3g)
158              Ignore character case when accessing a file (FOO, Foo, foo, etc.
159              designate the same file). All files  are  displayed  with  lower
160              case in directory listings.
161
162       remove_hiberfile
163              When the NTFS volume is hibernated, a read-write mount is denied
164              and a read-only mount is forced. One needs either to resume Win‐
165              dows  and  shutdown  it  properly, or use this option which will
166              remove the Windows hibernation file.  Please  note,  this  means
167              that the saved Windows session will be completely lost. Use this
168              option under your own responsibility.
169
170       atime, noatime, relatime
171              The atime option updates inode access time for each access.
172
173              The noatime option disables inode access time updates which  can
174              speed  up  file operations and prevent sleeping (notebook) disks
175              spinning up too often thus saving energy and disk lifetime.
176
177              The relatime option is very  similar  to  noatime.   It  updates
178              inode  access  times  relative  to  modify  or change time.  The
179              access time is only updated if the previous access time was ear‐
180              lier than the current modify or change time. Unlike noatime this
181              option doesn't break applications that need to know  if  a  file
182              has  been read since the last time it was modified.  This is the
183              default behaviour.
184
185       delay_mtime[= value]
186              Only update the file modification time and the file change  time
187              of  a  file  when it is closed or when the indicated delay since
188              the previous update has elapsed. The argument  is  a  number  of
189              seconds,  with a default value of 60.  This is mainly useful for
190              big files which are kept open for a long  time  and  written  to
191              without  changing  their  size, such as databases or file system
192              images mounted as loop.
193
194       show_sys_files
195              Show the metafiles in directory listings. Otherwise the  default
196              behaviour is to hide the metafiles, which are special files used
197              to store the NTFS structure. Please note  that  even  when  this
198              option  is  specified,  "$MFT" may not be visible due to a glibc
199              bug. Furthermore, irrespectively of  show_sys_files,  all  files
200              are  accessible  by  name,  for example you can always do "ls -l
201              '$UpCase'".
202
203       hide_hid_files
204              Hide the hidden files and directories in directory listings, the
205              hidden files and directories being the ones whose NTFS attribute
206              have the hidden flag set.  The hidden files will not be selected
207              when  using wildcards in commands, but all files and directories
208              remain accessible by full name, for example you can always  dis‐
209              play  the  Windows  trash  bin  directory  by  : "ls -ld '$RECY‐
210              CLE.BIN'".
211
212       hide_dot_files
213              Set the hidden flag in the NTFS attribute for created files  and
214              directories  whose  first  character  of the name is a dot. Such
215              files and directories normally do not appear in directory  list‐
216              ings,  and  when  the  flag is set they do not appear in Windows
217              directory displays either.  When a file  is  renamed  or  linked
218              with a new name, the hidden flag is adjusted to the latest name.
219
220       windows_names
221              This  option prevents files, directories and extended attributes
222              to be created with a name not allowed by windows, because
223
224                     - it contains some not allowed character,
225                     - or the last character is a space or a dot,
226                     - or the name is reserved.
227
228              The forbidden characters are the nine characters " * / : < > ? \
229              | and those whose code is less than 0x20, and the reserved names
230              are CON, PRN, AUX, NUL, COM1..COM9, LPT1..LPT9, with  no  suffix
231              or followed by a dot.
232
233              Existing such files can still be read (and renamed).
234
235       allow_other
236              This  option  overrides  the  security  measure restricting file
237              access to the user mounting the filesystem. This option is  only
238              allowed  to  root, but this restriction can be overridden by the
239              'user_allow_other' option in the /etc/fuse.conf file.
240
241       max_read=value
242              With this option the maximum size of read operations can be set.
243              The default is infinite.  Note that the size of read requests is
244              limited anyway to 32 pages (which is 128kbyte on i386).
245
246       silent Do nothing, without returning any  error,  on  chmod  and  chown
247              operations  and  on permission checking errors, when the permis‐
248              sions option is not set and no user  mapping  file  is  defined.
249              This  option  is on by default, and when set off (through option
250              no_def_opts) ownership and permissions  parameters  have  to  be
251              set.
252
253       no_def_opts
254              By default ntfs-3g acts as if "silent" (ignore permission errors
255              when permissions are not enabled), "allow_other" (allow any user
256              to  access  files)  and  "nonempty" (allow mounting on non-empty
257              directories) were set, and "no_def_opts" cancels  these  default
258              options.
259
260       streams_interface=value
261              This  option  controls  how  the  user can access Alternate Data
262              Streams (ADS) or in other words, named data streams. It  can  be
263              set  to,  one of none, windows or xattr. If the option is set to
264              none, the user will have no access to the named data streams. If
265              it  is  set  to windows (not possible with lowntfs-3g), then the
266              user can access them just like in Windows (eg. cat file:stream).
267              If  it's set to xattr, then the named data streams are mapped to
268              xattrs and user can manipulate them using {get,set}fattr  utili‐
269              ties. The default is xattr.
270
271       user_xattr
272              Same as streams_interface=xattr.
273
274       efs_raw
275              This  option should only be used in backup or restore situation.
276              It changes the apparent size of files and the behavior  of  read
277              and  write  operation  so  that encrypted files can be saved and
278              restored without being decrypted. The user.ntfs.efsinfo extended
279              attribute  has  also to be saved and restored for the file to be
280              decrypted.
281
282       compression
283              This option enables creating new transparently compressed  files
284              in directories marked for compression. A directory is marked for
285              compression by setting the bit 11 (value 0x00000800) in its Win‐
286              dows  attribute. In such a directory, new files are created com‐
287              pressed and new subdirectories are themselves  marked  for  com‐
288              pression.  The  option  and  the flag have no effect on existing
289              files. Currently this is the default option.
290
291       nocompression
292              This option disables creating new transparently compressed files
293              in directories marked for compression. Existing compressed files
294              can still be read and updated.
295
296       big_writes
297              This option prevents fuse from splitting write buffers  into  4K
298              chunks,  enabling  big  write buffers to be transferred from the
299              application in a single step (up to some system limit, generally
300              128K bytes).
301
302       debug  Makes ntfs-3g to print a lot of debug output from libntfs-3g and
303              FUSE.
304
305       no_detach
306              Makes ntfs-3g to not detach from terminal and print  some  debug
307              output.
308

USER MAPPING

310       NTFS  uses specific ids to record the ownership of files instead of the
311       uid and gid used by Linux. As a consequence a mapping between  the  ids
312       has  to  be  defined for ownerships to be recorded into NTFS and recog‐
313       nized.
314
315       By default, this mapping is fetched from the file  .NTFS-3G/UserMapping
316       located  in  the NTFS partition. The option usermapping= may be used to
317       define another location. When the option permissions is set and no map‐
318       ping file is found, a default mapping is used.
319
320       Each  line  in the user mapping file defines a mapping. It is organized
321       in three fields separated by colons. The first field identifies a  uid,
322       the second field identifies a gid and the third one identifies the cor‐
323       responding NTFS id, known as a SID. The uid and the  gid  are  optional
324       and defining both of them for the same SID is not recommended.
325
326       If  no  interoperation  with  Windows is needed, you can use the option
327       permissions to define a standard mapping. Alternately, you  may  define
328       your  own  mapping  by setting a single default mapping with no uid and
329       gid. In both cases, files created on Linux will appear  to  Windows  as
330       owned  by  a  foreign user, and files created on Windows will appear to
331       Linux as owned by root. Just copy the example below and replace  the  9
332       and  10-digit  numbers  by  any number not greater than 4294967295. The
333       resulting behavior is the same as the one with  the  option  permission
334       set with no ownership option and no user mapping file available.
335
336              ::S-1-5-21-3141592653-589793238-462643383-10000
337
338       If  a  strong interoperation with Windows is needed, the mapping has to
339       be defined for each user and group known in both system, and  the  SIDs
340       used  by  Windows has to be collected. This will lead to a user mapping
341       file like :
342
343              john::S-1-5-21-3141592653-589793238-462643383-1008
344              mary::S-1-5-21-3141592653-589793238-462643383-1009
345              :smith:S-1-5-21-3141592653-589793238-462643383-513
346              ::S-1-5-21-3141592653-589793238-462643383-10000
347
348
349       The utility ntfsusermap may be used to create such a user mapping file.
350

EXAMPLES

352       Mount /dev/sda1 to /mnt/windows:
353
354              ntfs-3g /dev/sda1 /mnt/windows
355       or
356              mount -t ntfs-3g /dev/sda1 /mnt/windows
357
358       Mount  the  ntfs  data  partition  /dev/sda3 to /mnt/data with standard
359       Linux permissions applied :
360
361              ntfs-3g -o permissions /dev/sda3 /mnt/data
362       or
363              mount -t ntfs-3g -o permissions /dev/sda3 /mnt/data
364
365       Read-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000
366       to be the owner of all files:
367
368              ntfs-3g /dev/sda5 /home/user/mnt -o ro,uid=1000
369
370       /etc/fstab entry for the above (the sixth and last field has to be zero
371       to avoid a file system check at boot time) :
372
373              /dev/sda5 /home/user/mnt ntfs-3g ro,uid=1000 0 0
374
375       Unmount /mnt/windows:
376
377              umount /mnt/windows
378
379

EXIT CODES

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

KNOWN ISSUES

387       Please see
388
389              http://www.tuxera.com/support/
390
391       for  common questions and known issues.  If you would find a new one in
392       the latest release of the software then please send an email describing
393       it   in   detail.   You   can  contact  the  development  team  on  the
394       ntfs-3g-devel@lists.sf.net address.
395

AUTHORS

397       ntfs-3g was based on and a major improvement to ntfsmount  and  libntfs
398       which  were  written  by  Yura  Pakhuchiy  and the Linux-NTFS team. The
399       improvements were made, the ntfs-3g project was initiated and currently
400       led   by  long  time  Linux-NTFS  team  developer  Szabolcs  Szakacsits
401       (szaka@tuxera.com).
402

THANKS

404       Several people made heroic efforts, often over five or more years which
405       resulted  the  ntfs-3g  driver.  Most  importantly they are Anton Alta‐
406       parmakov, Jean-Pierre André, Richard Russon, Szabolcs Szakacsits,  Yura
407       Pakhuchiy,  Yuval  Fledel,  and  the  author of the groundbreaking FUSE
408       filesystem development framework, Miklos Szeredi.
409

SEE ALSO

411       ntfs-3g.probe(8), ntfsprogs(8), attr(5), getfattr(1)
412
413
414
415ntfs-3g 2017.3.23                  Mar 2014                         NTFS-3G(8)
Impressum