path: root/src/ntfs-3g.8.in (plain)
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