path: root/src/ntfs-3g.8 (plain)
blob: ee5f7f8011b41535b8d4d4dffddd77b4f78322f9

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 2014.2.15"
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