xref: /linux/Documentation/filesystems/ntfs.rst (revision 7d1f84f1b94e79cb95d974ab3ec54cb3a4d64f5b)
1.. SPDX-License-Identifier: GPL-2.0
2
3=================================
4The Linux NTFS filesystem driver
5=================================
6
7
8.. Table of contents
9
10   - Overview
11   - Utilities support
12   - Linux file attributes
13   - Supported mount options
14
15
16Overview
17========
18
19NTFS is a Linux kernel filesystem driver that provides full read and write
20support for NTFS volumes. It is designed for high performance, modern
21kernel infrastructure (iomap, folio), and stable long-term maintenance.
22
23
24Utilities support
25=================
26
27The NTFS utilities project, called ntfsprogs-plus, provides mkfs.ntfs,
28fsck.ntfs, and other related tools (e.g., ntfsinfo, ntfsclone, etc.) for
29creating, checking, and managing NTFS volumes. These utilities can be used
30for filesystem testing with xfstests as well as for recovering corrupted
31NTFS devices.
32
33The project is available at:
34
35  https://github.com/ntfsprogs-plus/ntfsprogs-plus
36
37
38Linux file attributes
39=====================
40
41The driver supports lsattr(1) and chattr(1). Immutable, append-only, nodump
42and noatime are stored in a private ``$LINUXFLAGS`` extended attribute within the
43standard NTFS ``$EA``/``$EA_INFORMATION`` attributes. Its value is a
4432-bit little-endian bitmask: bit 0 is immutable, bit 1 is append-only,
45bit 2 is nodump, and bit 3 is noatime. Unknown bits are preserved when updating
46the flags; the entry is removed when the entire value becomes zero. These settings
47survive inode eviction, unmount and reboot. Direct writes to this EA
48through setxattr(2) or removexattr(2) are rejected; use chattr(1) instead.
49
50The noatime attribute (``chattr +A``) suppresses automatic access-time
51updates for the inode, including when mounted with ``strictatime``. It
52applies to directories as well as files, but is not inherited by newly
53created children. Use ``chattr -A`` to restore the mount's access-time policy.
54
55System metadata files and files protected by the ``sys_immutable`` mount
56option cannot have their immutable protection cleared with chattr(1).
57Protection derived solely from the mount option is not stored in the EA.
58Case folding is reported according to the mount options and cannot be
59configured per file. Compression and encryption are reported but cannot
60be changed through chattr(1).
61
62These Linux flags are enforced by Linux. Storing them in an NTFS EA does
63not make Windows enforce immutable, append-only, nodump or noatime semantics.
64
65
66Supported mount options
67=======================
68
69The NTFS driver supports the following mount options:
70
71======================= ====================================================
72iocharset=name          Character set to use for converting between
73                        the encoding is used for user visible filename and
74                        16 bit Unicode characters.
75
76nls=name                Deprecated option.  Still supported but please use
77                        iocharset=name in the future.
78
79uid=
80gid=
81umask=                  Provide default owner, group, and access mode mask.
82                        These options work as documented in mount(8).  By
83                        default, the files/directories are owned by root
84                        and he/she has read and write permissions, as well
85                        as browse permission for directories.  No one else
86                        has any access permissions.  I.e. the mode on all
87                        files is by default rw------- and
88                        for directories rwx------, a consequence of
89                        the default fmask=0177 and dmask=0077.
90                        Using a umask of zero will grant all permissions to
91                        everyone, i.e. all files and directories will have
92                        mode rwxrwxrwx.
93
94fmask=
95dmask=                  Instead of specifying umask which applies both to
96                        files and directories, fmask applies only to files
97                        and dmask only to directories.
98
99showmeta=<BOOL>
100show_sys_files=<BOOL>   If show_sys_files is specified, show the system
101                        files in directory listings.  Otherwise the default
102                        behaviour is to hide the system files.
103                        Note that even when show_sys_files is specified,
104                        "$MFT" will not be visible due to bugs/mis-features
105                        in glibc. Further, note that irrespective of
106                        show_sys_files, all files are accessible by name,
107                        i.e. you can always do "ls -l \$UpCase" for example
108                        to specifically show the system file containing
109                        the Unicode upcase table.
110
111case_sensitive=<BOOL>   If case_sensitive is specified, treat all filenames
112                        as case sensitive and create file names in
113                        the POSIX namespace (default behavior). Note,
114                        the Linux NTFS driver will never create short
115                        filenames and will remove them on rename/delete of
116                        the corresponding long file name. Note that files
117                        remain accessible via their short file name, if it
118                        exists.
119
120nocase=<BOOL>           If nocase is specified, treat filenames
121                        case-insensitively.
122
123disable_sparse=<BOOL>   If disable_sparse is specified, creation of sparse
124                        regions, i.e. holes, inside files is disabled for
125                        the volume (for the duration of this mount only).
126                        By default, creation of sparse regions is enabled,
127                        which is consistent with the behaviour of
128                        traditional Unix filesystems.
129
130errors=opt              Specify NTFS behavior on critical errors: panic,
131                        remount the partition in read-only mode or
132                        continue without doing anything (default behavior).
133
134mft_zone_multiplier=    Set the MFT zone multiplier for the volume (this
135                        setting is not persistent across mounts and can be
136                        changed from mount to mount but cannot be changed
137                        on remount).  Values of 1 to 4 are allowed, 1 being
138                        the default.  The MFT zone multiplier determines
139                        how much space is reserved for the MFT on the
140                        volume.  If all other space is used up, then the
141                        MFT zone will be shrunk dynamically, so this has no
142                        impact on the amount of free space.  However, it
143                        can have an impact on performance by affecting
144                        fragmentation of the MFT. In general use the
145                        default.  If you have a lot of small files then use
146                        a higher value.  The values have the following
147                        meaning:
148
149                        =====   =================================
150                        Value   MFT zone size (% of volume size)
151                        =====   =================================
152                          1             12.5%
153                          2             25%
154                          3             37.5%
155                          4             50%
156                        =====   =================================
157
158                        Note this option is irrelevant for read-only mount.
159
160preallocated_size=      Set preallocated size to optimize runlist merge
161                        overhead with small chunck size.(64KB size by
162                        default)
163
164acl=<BOOL>              Enable POSIX ACL support. When specified, POSIX
165                        ACLs stored in extended attributes are enforced.
166                        Default is off. Requires kernel config
167                        NTFS_FS_POSIX_ACL enabled.
168
169sys_immutable=<BOOL>    Make NTFS system files (e.g. $MFT, $LogFile,
170                        $Bitmap, $UpCase, etc.) immutable to user initiated
171                        modifications for extra safety. Default is off.
172
173nohidden=<BOOL>         Hide files and directories marked with the Windows
174                        "hidden" attribute. By default hidden items are
175                        shown.
176
177hide_dot_files=<BOOL>   Hide names beginning with a dot ("."). By default
178                        dot files are shown. When enabled, files and
179                        directories created with a leading '.' will be
180                        hidden from directory listings.
181
182windows_names=<BOOL>    Refuse creation/rename of files with characters or
183                        reserved device names disallowed on Windows (e.g.
184                        CON, NUL, AUX, COM1, LPT1, etc.). Default is off.
185discard=<BOOL>          Issue block device discard for clusters freed on
186                        file deletion/truncation to inform underlying
187                        storage.
188
189native_symlink=raw|rel  Configure how absolute symbolic links and mount
190                        points (junctions) are handled. Under "raw"
191                        (default), the absolute target path is returned
192                        as-is without translation. Under "rel", it is
193                        rewritten as a relative path anchored at
194                        the volume root.
195
196symlink=wsl|native      Configure how symbolic links are created. Under
197                        "wsl" (default), WSL (Windows Subsystem for
198                        Linux) compatible symlinks are created. Under
199                        "native", Windows native symbolic links are
200                        created.
201
202streams_interface=      Select the named-stream pathname interface:
203                        "none" (default) treats ':' as an ordinary filename
204                        character, while "windows" interprets the final
205                        component of a path such as "file:stream" as a named
206                        $DATA stream. In "windows" mode, filenames containing
207                        ':' are hidden from directory listings and cannot be
208                        addressed through the pathname interface. Only the
209                        file:stream form is recognized. Typed forms such
210                        as file::$DATA and file:stream:$DATA are not
211                        supported. The ioctl interface is available in both
212                        modes. The base file or directory must already exist
213                        before a pathname stream can be created. Creating
214                        file:stream does not create file. Removing a stream
215                        while it is open fails with -EBUSY. Removing the base
216                        file while a stream is open detaches the stream from
217                        the namespace; NTFS has no orphan-stream list, so a
218                        crash can leave that stream's data unreachable on
219                        disk.
220======================= ====================================================
221
222Named-stream ioctls
223===================
224
225The named-stream ioctl interface is available regardless of
226streams_interface. Open the base regular file or directory and use
227NTFS_IOC_STREAM_READ and NTFS_IOC_STREAM_WRITE with a
228struct ntfs_stream request. The request contains the stream name,
229byte offset, and transfer length. Write requests create the stream when it
230does not exist. Writes are not atomic. Error can leave partial data
231changes, an extended stream size, or a newly created stream. bytes_returned
232is valid only on success. Failed write does not report a completed byte
233count. Use NTFS_IOC_STREAM_REMOVE to remove a stream and NTFS_IOC_LIST_STREAMS
234to enumerate streams. Stream names are encoded with
235the mounted NLS by default. Set NTFS_STREAM_FL_UTF16 to pass or receive
236raw UTF-16LE names. These ioctls transfer stream data directly and do not
237return a separate stream file descriptor.
238