blob: 3134d210d3e1f9c4db6fc350aee31e5b5cac55b3
1 | .\" Copyright (c) 2005-2006 Yura Pakhuchiy. |
2 | .\" Copyright (c) 2005 Richard Russon. |
3 | .\" Copyright (c) 2006-2009 Szabolcs Szakacsits. |
4 | .\" Copyright (c) 2009 Jean-Pierre Andre |
5 | .\" This file may be copied under the terms of the GNU Public License. |
6 | .\" |
7 | .TH NTFS-3G 8 "February 2010" "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 Access Handling and Security |
40 | By default, files and directories are owned by the effective |
41 | user and group of the mounting process and everybody has |
42 | full read, write, execution and directory browsing permissions. |
43 | You can also assign permissions to a single user by using the |
44 | .B uid |
45 | and/or the |
46 | .B gid |
47 | options together with the |
48 | .B umask, |
49 | or |
50 | .B fmask |
51 | and |
52 | .B dmask |
53 | options. |
54 | .PP |
55 | Doing so, Windows users have full access to the files created by |
56 | .B ntfs-3g. |
57 | .PP |
58 | But, by defining a Windows-to-Linux user mapping in the file |
59 | \fB.NTFS-3G/UserMapping\fP, you can benefit from the full ownership and |
60 | permissions features as defined by Posix and those ownership and |
61 | permissions will be applied to Windows users and conversely. |
62 | .PP |
63 | If |
64 | .B ntfs-3g |
65 | is set setuid-root then non-root users will |
66 | be also able to mount volumes. |
67 | .SS Windows Filename Compatibility |
68 | NTFS supports several filename namespaces: DOS, Win32 and POSIX. While the |
69 | \fBntfs-3g\fR driver handles all of them, it always creates new files in the |
70 | POSIX namespace for maximum portability and interoperability reasons. |
71 | This means that filenames are case sensitive and all characters are |
72 | allowed except '/' and '\\0'. This is perfectly legal on Windows, though |
73 | some application may get confused. If you find so then please report it |
74 | to the developer of the relevant Windows software. |
75 | .SS Alternate Data Streams (ADS) |
76 | NTFS stores all data in streams. Every file has exactly one unnamed |
77 | data stream and can have many named data streams. The size of a file is the |
78 | size of its unnamed data stream. By default, \fBntfs-3g\fR will only read |
79 | the unnamed data stream. |
80 | .PP |
81 | By using the options "streams_interface=windows", with the ntfs-3g driver |
82 | (not possible with lowntfs-3g), you will be able to read any named data |
83 | streams, simply by specifying the stream's name after a colon. |
84 | For example: |
85 | .RS |
86 | .sp |
87 | cat some.mp3:artist |
88 | .sp |
89 | .RE |
90 | Named data streams act like normal files, so you can read from them, write to |
91 | them and even delete them (using rm). You can list all the named data streams |
92 | a file has by getting the "ntfs.streams.list" extended attribute. |
93 | .SH OPTIONS |
94 | Below is a summary of the options that \fBntfs-3g\fR accepts. |
95 | .TP |
96 | \fBuid=\fP\fIvalue\fP and \fBgid=\fP\fIvalue\fP |
97 | Set the owner and the group of files and directories. The values are numerical. |
98 | The defaults are the uid and gid of the current process. |
99 | .TP |
100 | .BI umask= value |
101 | Set the bitmask of the file and directory permissions that are not |
102 | present. The value is given in octal. The default value is 0 which |
103 | means full access to everybody. |
104 | .TP |
105 | .BI fmask= value |
106 | Set the bitmask of the file permissions that are not present. |
107 | The value is given in octal. The default value is 0 which |
108 | means full access to everybody. |
109 | .TP |
110 | .BI dmask= value |
111 | Set the bitmask of the directory permissions that are not |
112 | present. The value is given in octal. The default value is 0 which |
113 | means full access to everybody. |
114 | .TP |
115 | .BI usermapping= file-name |
116 | Use file \fIfile-name\fP as the user mapping file instead of the default |
117 | \fB.NTFS-3G/UserMapping\fP. If \fIfile-name\fP defines a full path, the |
118 | file must be located on a partition previously mounted. If it defines a |
119 | relative path, it is interpreted relative to the root of NTFS partition |
120 | being mounted. |
121 | .P |
122 | .RS |
123 | When a user mapping file is defined, the options \fBuid=\fP, \fBgid=\fP, |
124 | \fBumask=\fP, \fBfmask=\fP, \fBdmask=\fP and \fBdsilent=\fP are ignored. |
125 | .RE |
126 | .TP |
127 | .B default_permissions |
128 | Use standard access control. This option requires either a user mapping |
129 | file to be present, or the options \fIuid=\fP and \fIgid=\fP of a user |
130 | to be defined. This option is set by default when a user mapping file |
131 | or an ownership related option is present. |
132 | .TP |
133 | .B inherit |
134 | When creating a new file, set its initial ownership and protections |
135 | according to inheritance rules defined in parent directory. These rules |
136 | deviate from Posix specifications, but yield a better Windows |
137 | compatibility. A valid user mapping file is required for this option |
138 | to be effective. |
139 | .TP |
140 | .B ro |
141 | Mount filesystem read\-only. Useful if Windows is hibernated or the |
142 | NTFS journal file is unclean. |
143 | .TP |
144 | .BI locale= value |
145 | This option can be useful when wanting a language specific locale environment. |
146 | It is however discouraged as it leads to files with untranslatable chars |
147 | to not be visible. Please see more information about this topic at |
148 | http://ntfs-3g.org/support.html#locale |
149 | .TP |
150 | .B force |
151 | Force the mounting even if the NTFS logfile is unclean. The logfile |
152 | will be unconditionally cleared. Use this option with caution and for |
153 | your own responsibility. |
154 | .TP |
155 | .B remove_hiberfile |
156 | Unlike in case of read-only mount, the read-write mount is denied if |
157 | the NTFS volume is hibernated. One needs either to resume Windows and |
158 | shutdown it properly, or use this option which will remove the Windows |
159 | hibernation file. Please note, this means that the saved Windows |
160 | session will be completely lost. Use this option for your own |
161 | responsibility. |
162 | .TP |
163 | .B atime, noatime, relatime |
164 | The |
165 | .B atime |
166 | option updates inode access time for each access. |
167 | |
168 | The |
169 | .B noatime |
170 | option disables inode access time updates which can speed up |
171 | file operations and prevent sleeping (notebook) disks spinning |
172 | up too often thus saving energy and disk lifetime. |
173 | |
174 | The |
175 | .B relatime |
176 | option is very similar to |
177 | .B noatime. |
178 | It updates inode access times relative to modify or change time. |
179 | The access time is only updated if the previous access time was earlier |
180 | than the current modify or change time. Unlike |
181 | .B noatime |
182 | this option doesn't break applications that need to know |
183 | if a file has been read since the last time it was modified. |
184 | This is the default behaviour. |
185 | .TP |
186 | .B show_sys_files |
187 | Show the system files in directory listings. |
188 | Otherwise the default behaviour is to hide the system files. |
189 | Please note that even when this option is specified, "$MFT" |
190 | may not be visible due to a glibc bug. |
191 | Furthermore, irrespectively of show_sys_files, all |
192 | files are accessible by name, for example you can always do |
193 | "ls \-l '$UpCase'". |
194 | .TP |
195 | .B allow_other |
196 | This option overrides the security measure restricting file access |
197 | to the user mounting the filesystem. This option is only |
198 | allowed to root, but this restriction can be overridden by |
199 | the 'user_allow_other' option in the /etc/fuse.conf file. |
200 | .TP |
201 | .BI 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 to 32 pages (which is 128kbyte on i386). |
205 | .TP |
206 | .B silent |
207 | Do nothing on chmod and chown operations, but do not return error |
208 | when the user mapping file required by these operations is not defined. |
209 | This option is on by default. |
210 | .TP |
211 | .B no_def_opts |
212 | By default ntfs-3g acts as if "silent" were set, and |
213 | this option cancel this default behavior. |
214 | .TP |
215 | .BI streams_interface= value |
216 | This option controls how the user can access Alternate Data Streams (ADS) |
217 | or in other words, named data streams. It can be set |
218 | to, one of \fBnone\fR, \fBwindows\fR or \fBxattr\fR. If the option is set to |
219 | \fBnone\fR, the user will have no access to the named data streams. If it's set |
220 | to \fBwindows\fR, then the user can access them just like in Windows (eg. cat |
221 | file:stream). If it's set to \fBxattr\fR, then the named data streams are |
222 | mapped to xattrs and user can manipulate them using \fB{get,set}fattr\fR |
223 | utilities. The default is \fBxattr\fR. |
224 | .TP |
225 | .B user_xattr |
226 | Same as \fBstreams_interface=\fP\fIxattr\fP. |
227 | .TP |
228 | .B efs_raw |
229 | This option should only be used in backup or restore situation. |
230 | It changes the apparent size of files and the behavior of read and |
231 | write operation so that encrypted files can be saved and restored |
232 | without being decrypted. The \fBuser.ntfs.efsinfo\fP extended attribute |
233 | has also to be saved and restored for the file to be decrypted. |
234 | .TP |
235 | .B debug |
236 | Makes ntfs-3g to not detach from terminal and print a lot of debug output from |
237 | libntfs-3g and FUSE. |
238 | .TP |
239 | .B no_detach |
240 | Same as above but with less debug output. |
241 | .SH USER MAPPING |
242 | NTFS uses specific ids to record the ownership of files instead of |
243 | the \fBuid\fP and \fBgid\fP used by Linux. As a consequence a mapping |
244 | between the ids has to be defined for ownerships to be recorded into |
245 | NTFS and recognized. |
246 | .P |
247 | By default this mapping is fetched from the file \fB.NTFS-3G/UserMapping\fP |
248 | located in the NTFS partition. The option \fBusermapping=\fP may be used |
249 | to define another location. |
250 | .P |
251 | Each line in the user mapping file defines a mapping. It is organized |
252 | in three fields separated by colons. The first field identifies a \fBuid\fP, |
253 | the second field identifies a \fBgid\fP and the third one identifies the |
254 | corresponding NTFS id, known as a \fBSID\fP. The \fBuid\fP and the \fBgid\fP |
255 | are optional and defining both of them for the same \fBSID\fP is not |
256 | recommended. |
257 | .P |
258 | If no interoperation with Windows is needed, a single default mapping |
259 | with no uid and gid can be used. Just copy the example below and replace |
260 | the 9 and 10-digit numbers by any number not greater than 4294967295. |
261 | .RS |
262 | .sp |
263 | .B ::S-1-5-21-3141592653-589793238-462643383-10000 |
264 | .sp |
265 | .RE |
266 | If interoperation with Windows is needed, the mapping has to be defined |
267 | for each user and group known in both system, and the \fBSID\fPs used |
268 | by Windows has to be collected. This will lead to a user mapping file |
269 | like : |
270 | .RS |
271 | .sp |
272 | .B john::S-1-5-21-3141592653-589793238-462643383-1008 |
273 | .B mary::S-1-5-21-3141592653-589793238-462643383-1009 |
274 | .B :smith:S-1-5-21-3141592653-589793238-462643383-513 |
275 | .B ::S-1-5-21-3141592653-589793238-462643383-10000 |
276 | .sp |
277 | .RE |
278 | .P |
279 | The utility \fBntfs-3g.usermap\fP may be used to create the user mapping file. |
280 | .SH EXAMPLES |
281 | Mount /dev/sda1 to /mnt/windows: |
282 | .RS |
283 | .sp |
284 | .B ntfs-3g /dev/sda1 /mnt/windows |
285 | .sp |
286 | .RE |
287 | or |
288 | .RS |
289 | .sp |
290 | .B mount -t ntfs-3g /dev/sda1 /mnt/windows |
291 | .sp |
292 | .RE |
293 | Read\-only mount /dev/sda5 to /home/user/mnt and make user with uid 1000 |
294 | to be the owner of all files: |
295 | .RS |
296 | .sp |
297 | .B ntfs-3g /dev/sda5 /home/user/mnt \-o ro,uid=1000 |
298 | .sp |
299 | .RE |
300 | /etc/fstab entry for the above: |
301 | .RS |
302 | .sp |
303 | .B /dev/sda5 /home/user/mnt ntfs\-3g ro,uid=1000 0 0 |
304 | .sp |
305 | .RE |
306 | Unmount /mnt/windows: |
307 | .RS |
308 | .sp |
309 | .B umount /mnt/windows |
310 | .sp |
311 | .RE |
312 | .SH EXIT CODES |
313 | To facilitate the use of the |
314 | .B ntfs-3g |
315 | driver in scripts, an exit code is returned to give an indication of the |
316 | mountability status of a volume. Value 0 means success, and all other |
317 | ones mean an error. The unique error codes are documented in the |
318 | .BR ntfs-3g.probe (8) |
319 | manual page. |
320 | .SH KNOWN ISSUES |
321 | Please see |
322 | .RS |
323 | .sp |
324 | http://www.tuxera.com/support/ |
325 | .sp |
326 | .RE |
327 | for common questions and known issues. |
328 | If you would find a new one in the latest release of |
329 | the software then please send an email describing it |
330 | in detail. You can contact the |
331 | development team on the ntfs\-3g\-devel@lists.sf.net |
332 | address. |
333 | .SH AUTHORS |
334 | .B ntfs-3g |
335 | was based on and a major improvement to ntfsmount and libntfs which were |
336 | written by Yura Pakhuchiy and the Linux-NTFS team. The improvements were |
337 | made, the ntfs-3g project was initiated and currently led by long time |
338 | Linux-NTFS team developer Szabolcs Szakacsits (szaka@tuxera.com). |
339 | .SH THANKS |
340 | Several people made heroic efforts, often over five or more |
341 | years which resulted the ntfs-3g driver. Most importantly they are |
342 | Anton Altaparmakov, Jean-Pierre André, Richard Russon, Szabolcs Szakacsits, |
343 | Yura Pakhuchiy, Yuval Fledel, and the author of the groundbreaking FUSE |
344 | filesystem development framework, Miklos Szeredi. |
345 | .SH SEE ALSO |
346 | .BR ntfs-3g.probe (8), |
347 | .BR ntfsprogs (8), |
348 | .BR attr (5), |
349 | .BR getfattr (1) |
350 |