blob: 42f2e2b12aa9f852b8bafa470439afc47e721caa
1 | .\" Copyright (c) 2005-2006 Yura Pakhuchiy. |
2 | .\" Copyright (c) 2005 Richard Russon. |
3 | .\" Copyright (c) 2006-2009 Szabolcs Szakacsits. |
4 | .\" Copyright (c) 2009-2012 Jean-Pierre Andre |
5 | .\" This file may be copied under the terms of the GNU Public License. |
6 | .\" |
7 | .TH NTFS-3G 8 "May 2012" "ntfs-3g @VERSION@" |
8 | .SH NAME |
9 | ntfs-3g \- Third Generation Read/Write NTFS Driver |
10 | .SH SYNOPSIS |
11 | .B ntfs-3g |
12 | \fB[-o \fIoption\fP\fB[,...]]\fR |
13 | .I volume mount_point |
14 | .br |
15 | .B mount \-t ntfs-3g |
16 | \fB[-o \fIoption\fP\fB[,...]]\fR |
17 | .I volume mount_point |
18 | .br |
19 | .B lowntfs-3g |
20 | \fB[-o \fIoption\fP\fB[,...]]\fR |
21 | .I volume mount_point |
22 | .br |
23 | .B mount \-t lowntfs-3g |
24 | \fB[-o \fIoption\fP\fB[,...]]\fR |
25 | .I volume mount_point |
26 | .SH DESCRIPTION |
27 | \fBntfs-3g\fR is an NTFS driver, which can create, remove, rename, move |
28 | files, directories, hard links, and streams; it can read and write files, |
29 | including streams, sparse files and transparently compressed files; it can |
30 | handle special files like symbolic links, devices, and FIFOs; moreover it |
31 | provides standard management of file ownership and permissions, including |
32 | POSIX ACLs. |
33 | .PP |
34 | It comes in two variants \fBntfs-3g\fR and \fBlowntfs-3g\fR with |
35 | a few differences mentioned below in relevant options descriptions. |
36 | .PP |
37 | The \fIvolume\fR to be mounted can be either a block device or |
38 | an image file. |
39 | .SS Windows hibernation and fast restarting |
40 | On computers which can be dual-booted into Windows or Linux, Windows has |
41 | to be fully shut down before booting into Linux, otherwise the NTFS file |
42 | systems on internal disks may be left in an inconsistent state and changes |
43 | made by Linux may be ignored by Windows. |
44 | .P |
45 | So, Windows may not be left in hibernation when starting Linux, in order |
46 | to avoid inconsistencies. Moreover, the fast restart feature available on |
47 | recent Windows systems has to be disabled. This can be achieved by issuing |
48 | as an Administrator the Windows command which disables both |
49 | hibernation and fast restarting : |
50 | .RS |
51 | .sp |
52 | powercfg /h off |
53 | .sp |
54 | .RE |
55 | .SS Access Handling and Security |
56 | By default, files and directories are owned by the effective |
57 | user and group of the mounting process, and everybody has |
58 | full read, write, execution and directory browsing permissions. |
59 | You can also assign permissions to a single user by using the |
60 | .B uid |
61 | and/or the |
62 | .B gid |
63 | options together with the |
64 | .B umask, |
65 | or |
66 | .B fmask |
67 | and |
68 | .B dmask |
69 | options. |
70 | .PP |
71 | Doing so, Windows users have full access to the files created by |
72 | .B ntfs-3g. |
73 | .PP |
74 | But, by setting the \fBpermissions\fR option, you can benefit from the full |
75 | ownership and permissions features as defined by POSIX. Moreover, by defining |
76 | a Windows-to-Linux user mapping, the ownerships and permissions are even |
77 | applied to Windows users and conversely. |
78 | .PP |
79 | If |
80 | .B ntfs-3g |
81 | is set setuid-root then non-root users will |
82 | be also able to mount volumes. |
83 | .SS Windows Filename Compatibility |
84 | NTFS supports several filename namespaces: DOS, Win32 and POSIX. While the |
85 | \fBntfs-3g\fR driver handles all of them, it always creates new files in the |
86 | POSIX namespace for maximum portability and interoperability reasons. |
87 | This means that filenames are case sensitive and all characters are |
88 | allowed except '/' and '\\0'. This is perfectly legal on Windows, though |
89 | some application may get confused. The option \fBwindows_names\fP may be |
90 | used to apply Windows restrictions to new file names. |
91 | .SS Alternate Data Streams (ADS) |
92 | NTFS stores all data in streams. Every file has exactly one unnamed |
93 | data stream and can have many named data streams. The size of a file is the |
94 | size of its unnamed data stream. By default, \fBntfs-3g\fR will only read |
95 | the unnamed data stream. |
96 | .PP |
97 | By using the options "streams_interface=windows", with the ntfs-3g driver |
98 | (not possible with lowntfs-3g), you will be able to read any named data |
99 | streams, simply by specifying the stream's name after a colon. |
100 | For example: |
101 | .RS |
102 | .sp |
103 | cat some.mp3:artist |
104 | .sp |
105 | .RE |
106 | Named data streams act like normal files, so you can read from them, write to |
107 | them and even delete them (using rm). You can list all the named data streams |
108 | a file has by getting the "ntfs.streams.list" extended attribute. |
109 | .SH OPTIONS |
110 | Below is a summary of the options that \fBntfs-3g\fR accepts. |
111 | .TP |
112 | \fBuid=\fP\fIvalue\fP and \fBgid=\fP\fIvalue\fP |
113 | Set the owner and the group of files and directories. The values are numerical. |
114 | The defaults are the uid and gid of the current process. |
115 | .TP |
116 | .BI umask= value |
117 | Set the bitmask of the file and directory permissions that are not |
118 | present. The value is given in octal. The default value is 0 which |
119 | means full access to everybody. |
120 | .TP |
121 | .BI fmask= value |
122 | Set the bitmask of the file permissions that are not present. |
123 | The value is given in octal. The default value is 0 which |
124 | means full access to everybody. |
125 | .TP |
126 | .BI dmask= value |
127 | Set the bitmask of the directory permissions that are not |
128 | present. The value is given in octal. The default value is 0 which |
129 | means full access to everybody. |
130 | .TP |
131 | .BI usermapping= file-name |
132 | Use file \fIfile-name\fP as the user mapping file instead of the default |
133 | \fB.NTFS-3G/UserMapping\fP. If \fIfile-name\fP defines a full path, the |
134 | file must be located on a partition previously mounted. If it defines a |
135 | relative path, it is interpreted relative to the root of NTFS partition |
136 | being mounted. |
137 | .P |
138 | .RS |
139 | When a user mapping file is defined, the options \fBuid=\fP, \fBgid=\fP, |
140 | \fBumask=\fP, \fBfmask=\fP, \fBdmask=\fP and \fBsilent\fP are ignored. |
141 | .RE |
142 | .TP |
143 | .B permissions |
144 | Set standard permissions on created files and use standard access control. |
145 | This option is set by default when a user mapping file is present. |
146 | .TP |
147 | .B acl |
148 | Enable setting Posix ACLs on created files and use them for access control. |
149 | This option is only available on specific builds. It is set by default |
150 | when a user mapping file is present and the |
151 | .B permissions |
152 | mount option is not set. |
153 | .TP |
154 | .B inherit |
155 | When creating a new file, set its initial protections |
156 | according to inheritance rules defined in parent directory. These rules |
157 | deviate from Posix specifications, but yield a better Windows |
158 | compatibility. The \fBcompression\fR option or a valid user mapping file |
159 | is required for this option to be effective. |
160 | .TP |
161 | .B ro |
162 | Mount filesystem read\-only. Useful if Windows is hibernated or the |
163 | NTFS journal file is unclean. |
164 | .TP |
165 | .BI locale= value |
166 | This option can be useful when wanting a language specific locale environment. |
167 | It is however discouraged as it leads to files with untranslatable chars |
168 | to not be visible. |
169 | .TP |
170 | .B force |
171 | This option is obsolete. It has been superseded by the \fBrecover\fR and |
172 | \fBnorecover\fR options. |
173 | .TP |
174 | .B recover |
175 | Recover and try to mount a partition which was not unmounted properly by |
176 | Windows. The Windows logfile is cleared, which may cause inconsistencies. |
177 | Currently this is the default option. |
178 | .TP |
179 | .B norecover |
180 | Do not try to mount a partition which was not unmounted properly by Windows. |
181 | .TP |
182 | .B ignore_case \fP(only with lowntfs-3g) |
183 | Ignore character case when accessing a file (\fBFOO\fR, \fBFoo\fR, \fBfoo\fR, |
184 | etc. designate the same file). All files are displayed with lower case in |
185 | directory listings. |
186 | .TP |
187 | .B remove_hiberfile |
188 | Unlike in case of read-only mount, the read-write mount is denied if |
189 | the NTFS volume is hibernated. One needs either to resume Windows and |
190 | shutdown it properly, or use this option which will remove the Windows |
191 | hibernation file. Please note, this means that the saved Windows |
192 | session will be completely lost. Use this option under your own |
193 | responsibility. |
194 | .TP |
195 | .B atime, noatime, relatime |
196 | The |
197 | .B atime |
198 | option updates inode access time for each access. |
199 | |
200 | The |
201 | .B noatime |
202 | option disables inode access time updates which can speed up |
203 | file operations and prevent sleeping (notebook) disks spinning |
204 | up too often thus saving energy and disk lifetime. |
205 | |
206 | The |
207 | .B relatime |
208 | option is very similar to |
209 | .B noatime. |
210 | It updates inode access times relative to modify or change time. |
211 | The access time is only updated if the previous access time was earlier |
212 | than the current modify or change time. Unlike |
213 | .B noatime |
214 | this option doesn't break applications that need to know |
215 | if a file has been read since the last time it was modified. |
216 | This is the default behaviour. |
217 | .TP |
218 | .B delay_mtime[= value] |
219 | Only update the file modification time and the file change time of a file |
220 | when it is closed or when the indicated delay since the previous update has |
221 | elapsed. The argument is a number of seconds, with a default value of 60. |
222 | This is mainly useful for big files which are kept open for a long |
223 | time and written to without changing their size, such as databases or file |
224 | system images mounted as loop. |
225 | .TP |
226 | .B show_sys_files |
227 | Show the metafiles in directory listings. Otherwise the default behaviour is |
228 | to hide the metafiles, which are special files used to store the NTFS |
229 | structure. Please note that even when this option is specified, "$MFT" may |
230 | not be visible due to a glibc bug. Furthermore, irrespectively of |
231 | show_sys_files, all files are accessible by name, for example you can always |
232 | do |
233 | "ls \-l '$UpCase'". |
234 | .TP |
235 | .B hide_hid_files |
236 | Hide the hidden files and directories in directory listings, the hidden files |
237 | and directories being the ones whose NTFS attribute have the hidden flag set. |
238 | The hidden files will not be selected when using wildcards in commands, |
239 | but all files and directories remain accessible by full name, for example you |
240 | can always display the Windows trash bin directory by : |
241 | "ls \-ld '$RECYCLE.BIN'". |
242 | .TP |
243 | .B hide_dot_files |
244 | Set the hidden flag in the NTFS attribute for created files and directories |
245 | whose first character of the name is a dot. Such files and directories |
246 | normally do not appear in directory listings, and when the flag is set |
247 | they do not appear in Windows directory displays either. |
248 | When a file is renamed or linked with a new name, the hidden flag is |
249 | adjusted to the latest name. |
250 | .TP |
251 | .B windows_names |
252 | This option prevents files, directories and extended attributes to be |
253 | created with a name not allowed by windows, either because it contains |
254 | some not allowed character (which are the nine characters " * / : < > ? \\ | and |
255 | those whose code is less than 0x20) or because the last character is a space |
256 | or a dot. Existing such files can still be read (and renamed). |
257 | .TP |
258 | .B allow_other |
259 | This option overrides the security measure restricting file access |
260 | to the user mounting the filesystem. This option is only |
261 | allowed to root, but this restriction can be overridden by |
262 | the 'user_allow_other' option in the /etc/fuse.conf file. |
263 | .TP |
264 | .BI max_read= value |
265 | With this option the maximum size of read operations can be set. |
266 | The default is infinite. Note that the size of read requests is |
267 | limited anyway to 32 pages (which is 128kbyte on i386). |
268 | .TP |
269 | .B silent |
270 | Do nothing, without returning any error, on chmod and chown operations, |
271 | when the \fBpermissions\fR option is not set and no user mapping file |
272 | is defined. This option is on by default. |
273 | .TP |
274 | .B no_def_opts |
275 | By default ntfs-3g acts as if "silent" (ignore errors on chmod and chown), |
276 | "allow_other" (allow any user to access files) and "nonempty" |
277 | (allow mounting on non-empty directories) were set, and "no_def_opts" |
278 | cancels these default options. |
279 | .TP |
280 | .BI streams_interface= value |
281 | This option controls how the user can access Alternate Data Streams (ADS) or |
282 | in other words, named data streams. It can be set to, one of \fBnone\fR, |
283 | \fBwindows\fR or \fBxattr\fR. If the option is set to \fBnone\fR, the user |
284 | will have no access to the named data streams. If it is set to \fBwindows\fR |
285 | (not possible with lowntfs-3g), then the user can access them just like in |
286 | Windows (eg. cat file:stream). If it's set to \fBxattr\fR, then the named |
287 | data streams are mapped to xattrs and user can manipulate them using |
288 | \fB{get,set}fattr\fR utilities. The default is \fBxattr\fR. |
289 | .TP |
290 | .B user_xattr |
291 | Same as \fBstreams_interface=\fP\fIxattr\fP. |
292 | .TP |
293 | .B efs_raw |
294 | This option should only be used in backup or restore situation. |
295 | It changes the apparent size of files and the behavior of read and |
296 | write operation so that encrypted files can be saved and restored |
297 | without being decrypted. The \fBuser.ntfs.efsinfo\fP extended attribute |
298 | has also to be saved and restored for the file to be decrypted. |
299 | .TP |
300 | .B compression |
301 | This option enables creating new transparently compressed files in |
302 | directories marked for compression. A directory is marked for compression by |
303 | setting the bit 11 (value 0x00000800) in its Windows attribute. In such a |
304 | directory, new files are created compressed and new subdirectories are |
305 | themselves marked for compression. The option and the flag have no effect |
306 | on existing files. |
307 | .TP |
308 | .B nocompression |
309 | This option disables creating new transparently compressed files in directories |
310 | marked for compression. Existing compressed files can still be read and |
311 | updated. Currently this is the default option. |
312 | .TP |
313 | .B big_writes |
314 | This option prevents fuse from splitting write buffers into 4K chunks, |
315 | enabling big write buffers to be transferred from the application in a |
316 | single step (up to some system limit, generally 128K bytes). |
317 | .TP |
318 | .B debug |
319 | Makes ntfs-3g to print a lot of debug output from libntfs-3g and FUSE. |
320 | .TP |
321 | .B no_detach |
322 | Makes ntfs-3g to not detach from terminal and print some debug output. |
323 | .SH USER MAPPING |
324 | NTFS uses specific ids to record the ownership of files instead of |
325 | the \fBuid\fP and \fBgid\fP used by Linux. As a consequence a mapping |
326 | between the ids has to be defined for ownerships to be recorded into |
327 | NTFS and recognized. |
328 | .P |
329 | By default, this mapping is fetched from the file \fB.NTFS-3G/UserMapping\fP |
330 | located in the NTFS partition. The option \fBusermapping=\fP may be used |
331 | to define another location. When the option permissions is set and |
332 | no mapping file is found, a default mapping is used. |
333 | .P |
334 | Each line in the user mapping file defines a mapping. It is organized |
335 | in three fields separated by colons. The first field identifies a \fBuid\fP, |
336 | the second field identifies a \fBgid\fP and the third one identifies the |
337 | corresponding NTFS id, known as a \fBSID\fP. The \fBuid\fP and the \fBgid\fP |
338 | are optional and defining both of them for the same \fBSID\fP is not |
339 | recommended. |
340 | .P |
341 | If no interoperation with Windows is needed, you can use the option |
342 | \fBpermissions\fP to define a standard mapping. Alternately, you may define |
343 | your own mapping by setting a single default mapping with no uid and gid. In |
344 | both cases, files created on Linux will appear to Windows as owned by a |
345 | foreign user, and files created on Windows will appear to Linux as owned by |
346 | root. Just copy the example below and replace the 9 and 10-digit numbers by |
347 | any number not greater than 4294967295. The resulting behavior is the same as |
348 | the one with the option permission set with no ownership option and no user |
349 | mapping file available. |
350 | .RS |
351 | .sp |
352 | .B ::S-1-5-21-3141592653-589793238-462643383-10000 |
353 | .sp |
354 | .RE |
355 | If a strong interoperation with Windows is needed, the mapping has to be |
356 | defined for each user and group known in both system, and the \fBSID\fPs used |
357 | by Windows has to be collected. This will lead to a user mapping file like : |
358 | .RS |
359 | .sp |
360 | .B john::S-1-5-21-3141592653-589793238-462643383-1008 |
361 | .B mary::S-1-5-21-3141592653-589793238-462643383-1009 |
362 | .B :smith:S-1-5-21-3141592653-589793238-462643383-513 |
363 | .B ::S-1-5-21-3141592653-589793238-462643383-10000 |
364 | .sp |
365 | .RE |
366 | .P |
367 | The utility \fBntfs-3g.usermap\fP may be used to create such a user |
368 | mapping file. |
369 | .SH EXAMPLES |
370 | Mount /dev/sda1 to /mnt/windows: |
371 | .RS |
372 | .sp |
373 | .B ntfs-3g /dev/sda1 /mnt/windows |
374 | .RE |
375 | or |
376 | .RS |
377 | .B mount -t ntfs-3g /dev/sda1 /mnt/windows |
378 | .sp |
379 | .RE |
380 | Mount the ntfs data partition /dev/sda3 to /mnt/data with standard Linux |
381 | permissions applied : |
382 | .RS |
383 | .sp |
384 | .B ntfs-3g -o permissions /dev/sda3 /mnt/data |
385 | .RE |
386 | or |
387 | .RS |
388 | .B mount -t ntfs-3g -o permissions /dev/sda3 /mnt/data |
389 | .sp |
390 | .RE |
391 | Read\-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000 |
392 | to be the owner of all files: |
393 | .RS |
394 | .sp |
395 | .B ntfs-3g /dev/sda5 /home/user/mnt \-o ro,uid=1000 |
396 | .sp |
397 | .RE |
398 | /etc/fstab entry for the above (the sixth and last field has to be zero to |
399 | avoid a file system check at boot time) : |
400 | .RS |
401 | .sp |
402 | .B /dev/sda5 /home/user/mnt ntfs\-3g ro,uid=1000 0 0 |
403 | .sp |
404 | .RE |
405 | Unmount /mnt/windows: |
406 | .RS |
407 | .sp |
408 | .B umount /mnt/windows |
409 | .sp |
410 | .RE |
411 | .SH EXIT CODES |
412 | To facilitate the use of the |
413 | .B ntfs-3g |
414 | driver in scripts, an exit code is returned to give an indication of the |
415 | mountability status of a volume. Value 0 means success, and all other |
416 | ones mean an error. The unique error codes are documented in the |
417 | .BR ntfs-3g.probe (8) |
418 | manual page. |
419 | .SH KNOWN ISSUES |
420 | Please see |
421 | .RS |
422 | .sp |
423 | http://www.tuxera.com/support/ |
424 | .sp |
425 | .RE |
426 | for common questions and known issues. |
427 | If you would find a new one in the latest release of |
428 | the software then please send an email describing it |
429 | in detail. You can contact the |
430 | development team on the ntfs\-3g\-devel@lists.sf.net |
431 | address. |
432 | .SH AUTHORS |
433 | .B ntfs-3g |
434 | was based on and a major improvement to ntfsmount and libntfs which were |
435 | written by Yura Pakhuchiy and the Linux-NTFS team. The improvements were |
436 | made, the ntfs-3g project was initiated and currently led by long time |
437 | Linux-NTFS team developer Szabolcs Szakacsits (szaka@tuxera.com). |
438 | .SH THANKS |
439 | Several people made heroic efforts, often over five or more |
440 | years which resulted the ntfs-3g driver. Most importantly they are |
441 | Anton Altaparmakov, Jean-Pierre André, Richard Russon, Szabolcs Szakacsits, |
442 | Yura Pakhuchiy, Yuval Fledel, and the author of the groundbreaking FUSE |
443 | filesystem development framework, Miklos Szeredi. |
444 | .SH SEE ALSO |
445 | .BR ntfs-3g.probe (8), |
446 | .BR ntfsprogs (8), |
447 | .BR attr (5), |
448 | .BR getfattr (1) |
449 |