Debian Codegraph @

upstream/debian-trixie/man5/xfs.5

raw
1 \." tbl
2 .TH xfs 5
3 .SH NAME
4 xfs \- layout, mount options, and supported file attributes for the XFS filesystem
5 .SH DESCRIPTION
6 An XFS filesystem can reside on a regular disk partition or on a
7 logical volume.
8 An XFS filesystem has up to three parts:
9 a data section, a log section, and a realtime section.
10 Using the default
11 .BR mkfs.xfs (8)
12 options, the realtime section is absent, and
13 the log area is contained within the data section.
14 The log section can be either separate from the data section
15 or contained within it.
16 The filesystem sections are divided into a certain number of
17 .IR blocks ,
18 whose size is specified at
19 .BR mkfs.xfs (8)
20 time with the
21 .B \-b
22 option.
23 .PP
24 The data section contains all the filesystem metadata
25 (inodes, directories, indirect blocks)
26 as well as the user file data for ordinary (non-realtime) files
27 and the log area if the log is
28 .I internal
29 to the data section.
30 The data section is divided into a number of
31 .IR "allocation groups" .
32 The number and size of the allocation groups are chosen by
33 .BR mkfs.xfs (8)
34 so that there is normally a small number of equal-sized groups.
35 The number of allocation groups controls the amount of parallelism
36 available in file and block allocation.
37 It should be increased from
38 the default if there is sufficient memory and a lot of allocation
39 activity.
40 The number of allocation groups should not be set very high,
41 since this can cause large amounts of CPU time to be used by
42 the filesystem, especially when the filesystem is nearly full.
43 More allocation groups are added (of the original size) when
44 .BR xfs_growfs (8)
45 is run.
46 .PP
47 The log section (or area, if it is internal to the data section)
48 is used to store changes to filesystem metadata while the
49 filesystem is running until those changes are made to the data
50 section.
51 It is written sequentially during normal operation and read only
52 during mount.
53 When mounting a filesystem after a crash, the log
54 is read to complete operations that were
55 in progress at the time of the crash.
56 .PP
57 The realtime section is used to store the data of realtime files.
58 These files had an attribute bit set through
59 .BR xfsctl (3)
60 after file creation, before any data was written to the file.
61 The realtime section is divided into a number of
62 .I extents
63 of fixed size (specified at
64 .BR mkfs.xfs (8)
65 time).
66 Each file in the realtime section has an extent size that
67 is a multiple of the realtime section extent size.
68 .PP
69 Each allocation group contains several data structures.
70 The first sector contains the superblock.
71 For allocation groups after the first,
72 the superblock is just a copy and is not updated after
73 .BR mkfs.xfs (8).
74 The next three sectors contain information for block and inode
75 allocation within the allocation group.
76 Also contained within each allocation group are data structures
77 to locate free blocks and inodes;
78 these are located through the header structures.
79 .PP
80 Each XFS filesystem is labeled with a Universal Unique
81 Identifier (UUID).
82 The UUID is stored in every allocation group header and
83 is used to help distinguish one XFS filesystem from another,
84 therefore you should avoid using
85 .BR dd (1)
86 or other block-by-block copying programs to copy XFS filesystems.
87 If two XFS filesystems on the same machine have the same UUID,
88 .BR xfsdump (8)
89 may become confused when doing incremental and resumed dumps.
90 .BR xfsdump (8)
91 and
92 .BR xfsrestore (8)
93 are recommended for making copies of XFS filesystems.
94 .SH OPERATIONS
95 Some functionality specific to the XFS filesystem is accessible to
96 applications through the
97 .BR xfsctl (3)
98 and by-handle (see
99 .BR open_by_handle (3))
100 interfaces.
101 .SH MOUNT OPTIONS
102 The following XFS-specific mount options may be used when mounting
103 an XFS filesystem. Other generic options may be used as well; refer to the
104 .BR mount (8)
105 manual page for more details.
106 .TP
107 .B allocsize=size
108 Sets the buffered I/O end-of-file preallocation size when
109 doing delayed allocation writeout. Valid values for this
110 option are page size (typically 4KiB) through to 1GiB,
111 inclusive, in power-of-2 increments.
112 .sp
113 The default behavior is for dynamic end-of-file
114 preallocation size, which uses a set of heuristics to
115 optimise the preallocation size based on the current
116 allocation patterns within the file and the access patterns
117 to the file. Specifying a fixed allocsize value turns off
118 the dynamic behavior.
119 .TP
120 .BR attr2 | noattr2
121 Note: These options have been
122 .B deprecated
123 as of kernel v5.10; The noattr2 option will be removed no
124 earlier than in September 2025 and attr2 option will be immutable
125 default.
126 .sp
127 The options enable/disable an "opportunistic" improvement to
128 be made in the way inline extended attributes are stored
129 on-disk. When the new form is used for the first time when
130 attr2 is selected (either when setting or removing extended
131 attributes) the on-disk superblock feature bit field will be
132 updated to reflect this format being in use.
133 .sp
134 The default behavior is determined by the on-disk feature
135 bit indicating that attr2 behavior is active. If either
136 mount option it set, then that becomes the new default used
137 by the filesystem.
138 .sp
139 CRC enabled filesystems always use the attr2 format, and so
140 will reject the noattr2 mount option if it is set.
141 .TP
142 .BR dax=value
143 Set CPU direct access (DAX) behavior for the current filesystem. This mount
144 option accepts the following values:
145
146 "dax=inode" DAX will be enabled only on regular files with FS_XFLAG_DAX applied.
147
148 "dax=never" DAX will not be enabled for any files. FS_XFLAG_DAX will be ignored.
149
150 "dax=always" DAX will be enabled for all regular files, regardless of the
151 FS_XFLAG_DAX state.
152
153 If no option is used when mounting a filesystem stored on a DAX capable device,
154 dax=inode will be used as default.
155
156 For details regarding DAX behavior in kernel, please refer to kernel's
157 documentation at filesystems/dax.txt
158 .TP
159 .BR discard | nodiscard
160 Enable/disable the issuing of commands to let the block
161 device reclaim space freed by the filesystem. This is
162 useful for SSD devices, thinly provisioned LUNs and virtual
163 machine images, but may have a performance impact.
164 .sp
165 Note: It is currently recommended that you use the fstrim
166 application to discard unused blocks rather than the discard
167 mount option because the performance impact of this option
168 is quite severe. For this reason, nodiscard is the default.
169 .TP
170 .BR grpid | bsdgroups | nogrpid | sysvgroups
171 These options define what group ID a newly created file
172 gets. When grpid is set, it takes the group ID of the
173 directory in which it is created; otherwise it takes the
174 fsgid of the current process, unless the directory has the
175 setgid bit set, in which case it takes the gid from the
176 parent directory, and also gets the setgid bit set if it is
177 a directory itself.
178 .TP
179 .B filestreams
180 Make the data allocator use the filestreams allocation mode
181 across the entire filesystem rather than just on directories
182 configured to use it.
183 .TP
184 .BR ikeep | noikeep
185 Note: These options have been
186 .B deprecated
187 as of kernel v5.10; The noikeep option will be removed no
188 earlier than in September 2025 and ikeep option will be
189 immutable default.
190
191 .sp
192 When ikeep is specified, XFS does not delete empty inode
193 clusters and keeps them around on disk. When noikeep is
194 specified, empty inode clusters are returned to the free
195 space pool. noikeep is the default.
196 .TP
197 .BR inode32 | inode64
198 When inode32 is specified, it indicates that XFS limits
199 inode creation to locations which will not result in inode
200 numbers with more than 32 bits of significance.
201 .sp
202 When inode64 is specified, it indicates that XFS is allowed
203 to create inodes at any location in the filesystem,
204 including those which will result in inode numbers occupying
205 more than 32 bits of significance.
206 .sp
207 inode32 is provided for backwards compatibility with older
208 systems and applications, since 64 bits inode numbers might
209 cause problems for some applications that cannot handle
210 large inode numbers. If applications are in use which do
211 not handle inode numbers bigger than 32 bits, the inode32
212 option should be specified.
213 .sp
214 For kernel v3.7 and later, inode64 is the default.
215 .TP
216 .BR largeio | nolargeio
217 If "nolargeio" is specified, the optimal I/O reported in
218 st_blksize by stat(2) will be as small as possible to allow
219 user applications to avoid inefficient read/modify/write
220 I/O. This is typically the page size of the machine, as
221 this is the granularity of the page cache.
222 .sp
223 If "largeio" specified, a filesystem that was created with a
224 "swidth" specified will return the "swidth" value (in bytes)
225 in st_blksize. If the filesystem does not have a "swidth"
226 specified but does specify an "allocsize" then "allocsize"
227 (in bytes) will be returned instead. Otherwise the behavior
228 is the same as if "nolargeio" was specified. nolargeio
229 is the default.
230 .TP
231 .B logbufs=value
232 Set the number of in-memory log buffers. Valid numbers
233 range from 2\(en8 inclusive.
234 .sp
235 The default value is 8 buffers.
236 .sp
237 If the memory cost of 8 log buffers is too high on small
238 systems, then it may be reduced at some cost to performance
239 on metadata intensive workloads. The logbsize option below
240 controls the size of each buffer and so is also relevant to
241 this case.
242 .TP
243 .B logbsize=value
244 Set the size of each in-memory log buffer. The size may be
245 specified in bytes, or in kibibytes (KiB) with a "k" suffix.
246 Valid sizes for version 1 and version 2 logs are 16384 (value=16k)
247 and 32768 (value=32k). Valid sizes for version 2 logs also
248 include 65536 (value=64k), 131072 (value=128k) and 262144 (value=256k). The
249 logbsize must be an integer multiple of the log
250 stripe unit configured at mkfs time.
251 .sp
252 The default value for version 1 logs is 32768, while the
253 default value for version 2 logs is max(32768, log_sunit).
254 .TP
255 .BR logdev=device " and " rtdev=device
256 Use an external log (metadata journal) and/or real-time device.
257 An XFS filesystem has up to three parts: a data section, a log
258 section, and a real-time section. The real-time section is
259 optional, and the log section can be separate from the data
260 section or contained within it.
261 .TP
262 .B noalign
263 Data allocations will not be aligned at stripe unit
264 boundaries. This is only relevant to filesystems created
265 with non-zero data alignment parameters (sunit, swidth) by
266 mkfs.
267 .TP
268 .B norecovery
269 The filesystem will be mounted without running log recovery.
270 If the filesystem was not cleanly unmounted, it is likely to
271 be inconsistent when mounted in "norecovery" mode.
272 Some files or directories may not be accessible because of this.
273 Filesystems mounted "norecovery" must be mounted read-only or
274 the mount will fail.
275 .TP
276 .B nouuid
277 Don't check for double mounted file systems using the file
278 system uuid. This is useful to mount LVM snapshot volumes,
279 and often used in combination with "norecovery" for mounting
280 read-only snapshots.
281 .TP
282 .B noquota
283 Forcibly turns off all quota accounting and enforcement
284 within the filesystem.
285 .TP
286 .B uquota/usrquota/quota/uqnoenforce/qnoenforce
287 User disk quota accounting enabled, and limits (optionally)
288 enforced. Refer to xfs_quota(8) for further details.
289 .TP
290 .B gquota/grpquota/gqnoenforce
291 Group disk quota accounting enabled and limits (optionally)
292 enforced. Refer to xfs_quota(8) for further details.
293 .TP
294 .B pquota/prjquota/pqnoenforce
295 Project disk quota accounting enabled and limits (optionally)
296 enforced. Refer to xfs_quota(8) for further details.
297 .TP
298 .BR sunit=value " and " swidth=value
299 Used to specify the stripe unit and width for a RAID device
300 or a stripe volume. "value" must be specified in 512-byte
301 block units. These options are only relevant to filesystems
302 that were created with non-zero data alignment parameters.
303 .sp
304 The sunit and swidth parameters specified must be compatible
305 with the existing filesystem alignment characteristics. In
306 general, that means the only valid changes to sunit are
307 increasing it by a power-of-2 multiple. Valid swidth values
308 are any integer multiple of a valid sunit value.
309 .sp
310 Typically the only time these mount options are necessary if
311 after an underlying RAID device has had it's geometry
312 modified, such as adding a new disk to a RAID5 lun and
313 reshaping it.
314 .TP
315 .B swalloc
316 Data allocations will be rounded up to stripe width boundaries
317 when the current end of file is being extended and the file
318 size is larger than the stripe width size.
319 .TP
320 .B wsync
321 When specified, all filesystem namespace operations are
322 executed synchronously. This ensures that when the namespace
323 operation (create, unlink, etc) completes, the change to the
324 namespace is on stable storage. This is useful in HA setups
325 where failover must not result in clients seeing
326 inconsistent namespace presentation during or after a
327 failover event.
328 .SH REMOVED MOUNT OPTIONS
329 The following mount options have been removed from the kernel, and will
330 yield mount failures if specified. Mount options are deprecated for
331 a significant period time prior to removal.
332 .TS
333 tab(@);
334 lbl.
335 Name@Removed
336 ----@-------
337 delaylog/[email protected]
338 [email protected]
339 [email protected]
340 osyncisdsync/[email protected]
341 barrier/[email protected]
342 .TE
343 .SH FILE ATTRIBUTES
344 The XFS filesystem supports setting the following file
345 attributes on Linux systems using the
346 .BR chattr (1)
347 utility:
348 .sp
349 .BR a " - append only"
350 .sp
351 .BR A " - no atime updates"
352 .sp
353 .BR d " - no dump"
354 .sp
355 .BR i " - immutable"
356 .sp
357 .BR S " - synchronous updates"
358 .sp
359 For descriptions of these attribute flags, please refer to the
360 .BR chattr (1)
361 man page.
362 .SH SEE ALSO
363 .BR chattr (1),
364 .BR xfsctl (3),
365 .BR mount (8),
366 .BR mkfs.xfs (8),
367 .BR xfs_info (8),
368 .BR xfs_admin (8),
369 .BR xfsdump (8),
370 .BR xfsrestore (8).