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       either by using the mount command or starting the drive.
27
28   Windows hibernation and fast restarting
29       On computers which can be dual-booted into Windows  or  Linux,  Windows
30       has to be fully shut down before booting into Linux, otherwise the NTFS
31       file systems on internal disks may be left in an inconsistent state and
32       changes made by Linux may be ignored by Windows.
33
34       So,  Windows may not be left in hibernation when starting Linux, in or‐
35       der to avoid inconsistencies. Moreover, the fast restart feature avail‐
36       able on recent Windows systems has to be disabled. This can be achieved
37       by issuing as an Administrator the Windows command which disables  both
38       hibernation and fast restarting :
39
40              powercfg /h off
41
42       If  either Windows is hibernated or its fast restart is enabled, parti‐
43       tions on internal disks are forced to be mounted in read-only mode.
44
45   Access Handling and Security
46       By default, files and directories are owned by the effective  user  and
47       group of the mounting process, and everybody has full read, write, exe‐
48       cution and directory browsing permissions.  You can also assign permis‐
49       sions to a single user by using the uid and/or the gid options together
50       with the umask, or fmask and dmask options.
51
52       Doing so, all Windows users have full access to the  files  created  by
53       ntfs-3g.
54
55       But,  by  setting the permissions option, you can benefit from the full
56       ownership and permissions features as defined by  POSIX.  Moreover,  by
57       defining  a  Windows-to-Linux  user mapping, the ownerships and permis‐
58       sions are even applied to Windows users and conversely.
59
60       If ntfs-3g is set setuid-root then non-root users will be also able  to
61       mount volumes.
62
63   Windows Filename Compatibility
64       NTFS  supports several filename namespaces: DOS, Win32 and POSIX. While
65       the ntfs-3g driver handles all of them, it always creates new files  in
66       the  POSIX  namespace for maximum portability and interoperability rea‐
67       sons.  This means that filenames are case sensitive and all  characters
68       are  allowed  except  '/' and '\0'. This is perfectly legal on Windows,
69       though some application may get confused. The option windows_names  may
70       be used to apply Windows restrictions to new file names.
71
72   Alternate Data Streams (ADS)
73       NTFS  stores  all  data  in streams. Every file has exactly one unnamed
74       data stream and can have many named data streams.  The size of  a  file
75       is  the size of its unnamed data stream.  By default, ntfs-3g will only
76       read the unnamed data stream.
77
78       By using the option streams_interface=windows, with the ntfs-3g  driver
79       (not possible with lowntfs-3g), you will be able to read any named data
80       streams, simply by specifying the stream name after a colon.  For exam‐
81       ple:
82
83              cat some.mp3:artist
84
85       Named  data  streams  act like normal files, so you can read from them,
86       write to them and even delete them (using rm).  You can  list  all  the
87       named data streams a file has by getting the ntfs.streams.list extended
88       attribute.
89

OPTIONS

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

USER MAPPING

330       NTFS uses specific ids to record the ownership of files instead of  the
331       uid (user id) and gid (group id) used by Linux. As a consequence a map‐
332       ping between the ids has to be defined for ownerships  to  be  recorded
333       into NTFS files and recognized.
334
335       By  default, this mapping is fetched from the file .NTFS-3G/UserMapping
336       located in the NTFS partition. The option usermapping= may be  used  to
337       define  another location. When the option **permissions** is set and no
338       mapping file is found, a default mapping is used.
339
340       Each line in the user mapping file defines a mapping. It  is  organized
341       in  three fields separated by colons. The first field identifies a uid,
342       the second field identifies a gid and the third one identifies the cor‐
343       responding  NTFS  id,  known as a SID. The uid and the gid are optional
344       and defining both of them for the same SID is not recommended.
345
346       If no interoperation with Windows is needed, you  can  use  the  option
347       permissions  to  define a standard mapping. Alternately, you may define
348       your own mapping by setting a single default mapping with  no  uid  and
349       gid.  In  both  cases, files created on Linux will appear to Windows as
350       owned by a foreign user, and files created on Windows  will  appear  to
351       Linux  as  owned by root. Just copy the example below and replace the 9
352       and 10-digit numbers by any number not greater than 4294967295. The re‐
353       sulting  behavior is the same as the one with the option permission set
354       with no ownership option and no user mapping file available.
355
356              ::S-1-5-21-3141592653-589793238-462643383-10000
357
358       If a strong interoperation with Windows is needed, the mapping  has  to
359       be  defined  for each user and group known to both system, and the SIDs
360       used by Windows has to be collected. This will lead to a  user  mapping
361       file like :
362
363              john::S-1-5-21-3141592653-589793238-462643383-1008
364              mary::S-1-5-21-3141592653-589793238-462643383-1009
365              :smith:S-1-5-21-3141592653-589793238-462643383-513
366              ::S-1-5-21-3141592653-589793238-462643383-10000
367
368
369       The utility ntfsusermap may be used to create such a user mapping file.
370

EXAMPLES

372       Mount /dev/sda1 to /mnt/windows:
373
374              ntfs-3g /dev/sda1 /mnt/windows
375       or
376              mount -t ntfs-3g /dev/sda1 /mnt/windows
377
378       Mount the ntfs data partition  /dev/sda3  to  /mnt/data  with  standard
379       Linux permissions applied :
380
381              ntfs-3g -o permissions /dev/sda3 /mnt/data
382       or
383              mount -t ntfs-3g -o permissions /dev/sda3 /mnt/data
384
385       Read-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000
386       to be the owner of all files:
387
388              ntfs-3g /dev/sda5 /home/user/mnt -o ro,uid=1000
389
390       /etc/fstab entry for the above (the sixth and last field has to be zero
391       to avoid a file system check at boot time) :
392
393              /dev/sda5 /home/user/mnt ntfs-3g ro,uid=1000 0 0
394
395       Unmount /mnt/windows:
396
397              umount /mnt/windows
398
399

EXIT CODES

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

KNOWN ISSUES

407       Please see
408
409              https://github.com/tuxera/ntfs-3g/wiki/NTFS-3G-FAQ
410
411       for common questions and known issues.  If you would find a new one  in
412       the  latest  release  of the software then please post an ntfs-3g issue
413       describing it in detail so that the development team can  be  aware  of
414       the issue and take care of it:
415
416              https://github.com/tuxera/ntfs-3g/issues
417
418

AUTHORS

420       ntfs-3g  was  based on and a major improvement to ntfsmount and libntfs
421       which were written by Yura Pakhuchiy and the Linux-NTFS team.  The  im‐
422       provements  were  made, the ntfs-3g project was initiated and currently
423       led  by  long  time  Linux-NTFS  team  developer  Szabolcs   Szakacsits
424       (szaka@tuxera.com).
425

THANKS

427       Several people made heroic efforts, often over five or more years which
428       resulted the ntfs-3g driver. Most  importantly  they  are  Anton  Alta‐
429       parmakov,  Jean-Pierre  André,  Erik  Larsson, Richard Russon, Szabolcs
430       Szakacsits, Yura Pakhuchiy, Yuval Fledel, and the author of the ground‐
431       breaking FUSE filesystem development framework, Miklos Szeredi.
432

SEE ALSO

434       ntfs-3g.probe(8), ntfsprogs(8), attr(5), getfattr(1)
435
436
437
438ntfs-3g 2022.10.3                  Aug 2021                         NTFS-3G(8)
Impressum