1NTFS-3G(8) System Manager's Manual NTFS-3G(8)
2
6 ntfs-3g - Third Generation Read/Write NTFS Driver
7
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
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 It comes in two variants ntfs-3g and lowntfs-3g with a few differences
23 mentioned below in relevant options descriptions.
24 The volume to be mounted can be either a block device or an image file.
26 Access Handling and Security
28 By default, files and directories are owned by the effective user and
29 group of the mounting process, and everybody has full read, write, exe‐
30 cution and directory browsing permissions. You can also assign permis‐
31 sions to a single user by using the uid and/or the gid options together
32 with the umask, or fmask and dmask options.
33 Doing so, Windows users have full access to the files created by
35 ntfs-3g.
36 But, by setting the permissions option, you can benefit from the full
38 ownership and permissions features as defined by POSIX. Moreover, by
39 defining a Windows-to-Linux user mapping, the ownerships and permis‐
40 sions are even applied to Windows users and conversely.
41 If ntfs-3g is set setuid-root then non-root users will be also able to
43 mount volumes.
44 Windows Filename Compatibility
46 NTFS supports several filename namespaces: DOS, Win32 and POSIX. While
47 the ntfs-3g driver handles all of them, it always creates new files in
48 the POSIX namespace for maximum portability and interoperability rea‐
49 sons. This means that filenames are case sensitive and all characters
50 are allowed except '/' and '\0'. This is perfectly legal on Windows,
51 though some application may get confused. The option windows_names may
52 be used to apply Windows restrictions to new file names.
53 Alternate Data Streams (ADS)
55 NTFS stores all data in streams. Every file has exactly one unnamed
56 data stream and can have many named data streams. The size of a file
57 is the size of its unnamed data stream. By default, ntfs-3g will only
58 read the unnamed data stream.
59 By using the options "streams_interface=windows", with the ntfs-3g
61 driver (not possible with lowntfs-3g), you will be able to read any
62 named data streams, simply by specifying the stream's name after a
63 colon. For example:
64 cat some.mp3:artist
66 Named data streams act like normal files, so you can read from them,
68 write to them and even delete them (using rm). You can list all the
69 named data streams a file has by getting the "ntfs.streams.list"
70 extended attribute.
71
73 Below is a summary of the options that ntfs-3g accepts.
74 uid=value and gid=value
76 Set the owner and the group of files and directories. The values
77 are numerical. The defaults are the uid and gid of the current
78 process.
79 umask=value
81 Set the bitmask of the file and directory permissions that are
82 not present. The value is given in octal. The default value is 0
83 which means full access to everybody.
84 fmask=value
86 Set the bitmask of the file permissions that are not present.
87 The value is given in octal. The default value is 0 which means
88 full access to everybody.
89 dmask=value
91 Set the bitmask of the directory permissions that are not
92 present. The value is given in octal. The default value is 0
93 which means full access to everybody.
94 usermapping=file-name
96 Use file file-name as the user mapping file instead of the
97 default .NTFS-3G/UserMapping. If file-name defines a full path,
98 the file must be located on a partition previously mounted. If
99 it defines a relative path, it is interpreted relative to the
100 root of NTFS partition being mounted.
101 When a user mapping file is defined, the options uid=, gid=,
103 umask=, fmask=, dmask= and silent are ignored.
104 permissions
106 Set standard permissions on created files and use standard
107 access control. This option is set by default when a user map‐
108 ping file is present.
109 acl Enable setting Posix ACLs on created files and use them for
111 access control. This option is only available on specific
112 builds. It is set by default when a user mapping file is present
113 and the permissions mount option is not set.
114 inherit
116 When creating a new file, set its initial ownership and protec‐
117 tions according to inheritance rules defined in parent direc‐
118 tory. These rules deviate from Posix specifications, but yield a
119 better Windows compatibility.
120 ro Mount filesystem read-only. Useful if Windows is hibernated or
122 the NTFS journal file is unclean.
123 locale=value
125 This option can be useful when wanting a language specific
126 locale environment. It is however discouraged as it leads to
127 files with untranslatable chars to not be visible.
128 force This option is obsolete. It has been superseded by the recover
130 and norecover options.
131 recover
133 Recover and try to mount a partition which was not unmounted
134 properly by Windows. The Windows logfile is cleared, which may
135 cause inconsistencies. Currently this is the default option.
136 norecover
138 Do not try to mount a partition which was not unmounted properly
139 by Windows.
140 ignore_case (only with lowntfs-3g)
142 Ignore character case when accessing a file (FOO, Foo, foo, etc.
143 designate the same file). All files are displayed with lower
144 case in directory listings.
145 remove_hiberfile
147 Unlike in case of read-only mount, the read-write mount is
148 denied if the NTFS volume is hibernated. One needs either to
149 resume Windows and shutdown it properly, or use this option
150 which will remove the Windows hibernation file. Please note,
151 this means that the saved Windows session will be completely
152 lost. Use this option under your own responsibility.
153 atime, noatime, relatime
155 The atime option updates inode access time for each access.
156 The noatime option disables inode access time updates which can
158 speed up file operations and prevent sleeping (notebook) disks
159 spinning up too often thus saving energy and disk lifetime.
160 The relatime option is very similar to noatime. It updates
162 inode access times relative to modify or change time. The
163 access time is only updated if the previous access time was ear‐
164 lier than the current modify or change time. Unlike noatime this
165 option doesn't break applications that need to know if a file
166 has been read since the last time it was modified. This is the
167 default behaviour.
168 show_sys_files
170 Show the metafiles in directory listings. Otherwise the default
171 behaviour is to hide the metafiles, which are special files used
172 to store the NTFS structure. Please note that even when this
173 option is specified, "$MFT" may not be visible due to a glibc
174 bug. Furthermore, irrespectively of show_sys_files, all files
175 are accessible by name, for example you can always do "ls -l
176 '$UpCase'".
177 hide_hid_files
179 Hide the hidden files and directories in directory listings, the
180 hidden files and directories being the ones whose NTFS attribute
181 have the hidden flag set. The hidden files will not be selected
182 when using wildcards in commands, but all files and directories
183 remain accessible by full name, for example you can always dis‐
184 play the Windows trash bin directory by : "ls -ld '$RECY‐
185 CLE.BIN'".
186 hide_dot_files
188 Set the hidden flag in the NTFS attribute for created files and
189 directories whose first character of the name is a dot. Such
190 files and directories normally do not appear in directory list‐
191 ings, and when the flag is set they do not appear in Windows
192 directory displays either.
193 windows_names
195 This option prevents files, directories and extended attributes
196 to be created with a name not allowed by windows, either because
197 it contains some not allowed character (which are the nine char‐
198 acters " * / : < > ? \ | and those whose code is less than 0x20)
199 or because the last character is a space or a dot. Existing such
200 files can still be read (and renamed).
201 allow_other
203 This option overrides the security measure restricting file
204 access to the user mounting the filesystem. This option is only
205 allowed to root, but this restriction can be overridden by the
206 'user_allow_other' option in the /etc/fuse.conf file.
207 max_read=value
209 With this option the maximum size of read operations can be set.
210 The default is infinite. Note that the size of read requests is
211 limited anyway to 32 pages (which is 128kbyte on i386).
212 silent Do nothing, without returning any error, on chmod and chown
214 operations, when the permissions option is not set and no user
215 mapping file is defined. This option is on by default.
216 no_def_opts
218 By default ntfs-3g acts as if "silent" (ignore errors on chmod
219 and chown), "allow_other" (allow any user to access files) and
220 "nonempty" (allow mounting on non-empty directories) were set,
221 and "no_def_opts" cancels these default options.
222 streams_interface=value
224 This option controls how the user can access Alternate Data
225 Streams (ADS) or in other words, named data streams. It can be
226 set to, one of none, windows or xattr. If the option is set to
227 none, the user will have no access to the named data streams. If
228 it is set to windows (not possible with lowntfs-3g), then the
229 user can access them just like in Windows (eg. cat file:stream).
230 If it's set to xattr, then the named data streams are mapped to
231 xattrs and user can manipulate them using {get,set}fattr utili‐
232 ties. The default is xattr.
233 user_xattr
235 Same as streams_interface=xattr.
236 efs_raw
238 This option should only be used in backup or restore situation.
239 It changes the apparent size of files and the behavior of read
240 and write operation so that encrypted files can be saved and
241 restored without being decrypted. The user.ntfs.efsinfo extended
242 attribute has also to be saved and restored for the file to be
243 decrypted.
244 compression
246 This option enables creating new transparently compressed files
247 in directories marked for compression. A directory is marked for
248 compression by setting the bit 11 (value 0x00000800) in its Win‐
249 dows attribute. In such a directory, new files are created com‐
250 pressed and new subdirectories are themselves marked for com‐
251 pression. The option and the flag have no effect on existing
252 files.
253 nocompression
255 This option disables creating new transparently compressed files
256 in directories marked for compression. Existing compressed files
257 can still be read and updated. Currently this is the default
258 option.
259 debug Makes ntfs-3g to print a lot of debug output from libntfs-3g and
261 FUSE.
262 no_detach
264 Makes ntfs-3g to not detach from terminal and print some debug
265 output.
266
268 NTFS uses specific ids to record the ownership of files instead of the
269 uid and gid used by Linux. As a consequence a mapping between the ids
270 has to be defined for ownerships to be recorded into NTFS and recog‐
271 nized.
272 By default, this mapping is fetched from the file .NTFS-3G/UserMapping
274 located in the NTFS partition. The option usermapping= may be used to
275 define another location. When the option permissions is set and no map‐
276 ping file is found, a default mapping is used.
277 Each line in the user mapping file defines a mapping. It is organized
279 in three fields separated by colons. The first field identifies a uid,
280 the second field identifies a gid and the third one identifies the cor‐
281 responding NTFS id, known as a SID. The uid and the gid are optional
282 and defining both of them for the same SID is not recommended.
283 If no interoperation with Windows is needed, you can use the option
285 permissions to define a standard mapping. Alternately, you may define
286 your own mapping by setting a single default mapping with no uid and
287 gid. In both cases, files created on Linux will appear to Windows as
288 owned by a foreign user, and files created on Windows will appear to
289 Linux as owned by root. Just copy the example below and replace the 9
290 and 10-digit numbers by any number not greater than 4294967295. The
291 resulting behavior is the same as the one with the option permission
292 set with no ownership option and no user mapping file available.
293 ::S-1-5-21-3141592653-589793238-462643383-10000
295 If a strong interoperation with Windows is needed, the mapping has to
297 be defined for each user and group known in both system, and the SIDs
298 used by Windows has to be collected. This will lead to a user mapping
299 file like :
300 john::S-1-5-21-3141592653-589793238-462643383-1008
302 mary::S-1-5-21-3141592653-589793238-462643383-1009
303 :smith:S-1-5-21-3141592653-589793238-462643383-513
304 ::S-1-5-21-3141592653-589793238-462643383-10000
305 The utility ntfs-3g.usermap may be used to create such a user mapping
308 file.
309
311 Mount /dev/sda1 to /mnt/windows:
312 ntfs-3g /dev/sda1 /mnt/windows
314 or
315 mount -t ntfs-3g /dev/sda1 /mnt/windows
316 Mount the ntfs data partition /dev/sda3 to /mnt/data with standard
318 Linux permissions applied :
319 ntfs-3g -o permissions /dev/sda3 /mnt/data
321 or
322 mount -t ntfs-3g -o permissions /dev/sda3 /mnt/data
323 Read-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000
325 to be the owner of all files:
326 ntfs-3g /dev/sda5 /home/user/mnt -o ro,uid=1000
328 /etc/fstab entry for the above:
330 /dev/sda5 /home/user/mnt ntfs-3g ro,uid=1000 0 0
331 Unmount /mnt/windows:
333 umount /mnt/windows
335
338 To facilitate the use of the ntfs-3g driver in scripts, an exit code is
339 returned to give an indication of the mountability status of a volume.
340 Value 0 means success, and all other ones mean an error. The unique
341 error codes are documented in the ntfs-3g.probe(8) manual page.
342
344 Please see
345 http://www.tuxera.com/support/
347 for common questions and known issues. If you would find a new one in
349 the latest release of the software then please send an email describing
350 it in detail. You can contact the development team on the
351 ntfs-3g-devel@lists.sf.net address.
352
354 ntfs-3g was based on and a major improvement to ntfsmount and libntfs
355 which were written by Yura Pakhuchiy and the Linux-NTFS team. The
356 improvements were made, the ntfs-3g project was initiated and currently
357 led by long time Linux-NTFS team developer Szabolcs Szakacsits
358 (szaka@tuxera.com).
359
361 Several people made heroic efforts, often over five or more years which
362 resulted the ntfs-3g driver. Most importantly they are Anton Alta‐
363 parmakov, Jean-Pierre André, Richard Russon, Szabolcs Szakacsits, Yura
364 Pakhuchiy, Yuval Fledel, and the author of the groundbreaking FUSE
365 filesystem development framework, Miklos Szeredi.
366
368 ntfs-3g.probe(8), ntfsprogs(8), attr(5), getfattr(1)
369ntfs-3g 2011.4.12 February 2010 NTFS-3G(8)