1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================
4 The SGI XFS Filesystem
5 ======================
6
7 XFS is a high performance journaling filesyste
8 on the SGI IRIX platform. It is completely mu
9 support large files and large filesystems, ext
10 variable block sizes, is extent based, and mak
11 Btrees (directories, extents, free space) to a
12 and scalability.
13
14 Refer to the documentation at https://xfs.wiki
15 for further details. This implementation is o
16 with the IRIX version of XFS.
17
18
19 Mount Options
20 =============
21
22 When mounting an XFS filesystem, the following
23
24 allocsize=size
25 Sets the buffered I/O end-of-file prea
26 doing delayed allocation writeout (def
27 Valid values for this option are page
28 through to 1GiB, inclusive, in power-o
29
30 The default behaviour is for dynamic e
31 preallocation size, which uses a set o
32 optimise the preallocation size based
33 allocation patterns within the file an
34 to the file. Specifying a fixed ``allo
35 the dynamic behaviour.
36
37 attr2 or noattr2
38 The options enable/disable an "opportu
39 be made in the way inline extended att
40 on-disk. When the new form is used fo
41 ``attr2`` is selected (either when set
42 attributes) the on-disk superblock fea
43 updated to reflect this format being i
44
45 The default behaviour is determined by
46 bit indicating that ``attr2`` behaviou
47 mount option is set, then that becomes
48 by the filesystem.
49
50 CRC enabled filesystems always use the
51 will reject the ``noattr2`` mount opti
52
53 discard or nodiscard (default)
54 Enable/disable the issuing of commands
55 device reclaim space freed by the file
56 useful for SSD devices, thinly provisi
57 machine images, but may have a perform
58
59 Note: It is currently recommended that
60 application to ``discard`` unused bloc
61 mount option because the performance i
62 is quite severe.
63
64 grpid/bsdgroups or nogrpid/sysvgroups (defau
65 These options define what group ID a n
66 gets. When ``grpid`` is set, it takes
67 directory in which it is created; othe
68 ``fsgid`` of the current process, unle
69 ``setgid`` bit set, in which case it t
70 parent directory, and also gets the ``
71 a directory itself.
72
73 filestreams
74 Make the data allocator use the filest
75 across the entire filesystem rather th
76 configured to use it.
77
78 ikeep or noikeep (default)
79 When ``ikeep`` is specified, XFS does
80 clusters and keeps them around on disk
81 specified, empty inode clusters are re
82 space pool.
83
84 inode32 or inode64 (default)
85 When ``inode32`` is specified, it indi
86 inode creation to locations which will
87 numbers with more than 32 bits of sign
88
89 When ``inode64`` is specified, it indi
90 to create inodes at any location in th
91 including those which will result in i
92 more than 32 bits of significance.
93
94 ``inode32`` is provided for backwards
95 systems and applications, since 64 bit
96 cause problems for some applications t
97 large inode numbers. If applications
98 not handle inode numbers bigger than 3
99 option should be specified.
100
101 largeio or nolargeio (default)
102 If ``nolargeio`` is specified, the opt
103 ``st_blksize`` by **stat(2)** will be
104 user applications to avoid inefficient
105 I/O. This is typically the page size
106 this is the granularity of the page ca
107
108 If ``largeio`` is specified, a filesys
109 ``swidth`` specified will return the `
110 in ``st_blksize``. If the filesystem d
111 specified but does specify an ``allocs
112 (in bytes) will be returned instead. O
113 is the same as if ``nolargeio`` was sp
114
115 logbufs=value
116 Set the number of in-memory log buffer
117 range from 2-8 inclusive.
118
119 The default value is 8 buffers.
120
121 If the memory cost of 8 log buffers is
122 systems, then it may be reduced at som
123 on metadata intensive workloads. The `
124 controls the size of each buffer and s
125 this case.
126
127 logbsize=value
128 Set the size of each in-memory log buf
129 specified in bytes, or in kilobytes wi
130 Valid sizes for version 1 and version
131 and 32768 (32k). Valid sizes for vers
132 include 65536 (64k), 131072 (128k) and
133 logbsize must be an integer multiple o
134 stripe unit configured at **mkfs(8)**
135
136 The default value for version 1 logs i
137 default value for version 2 logs is MA
138
139 logdev=device and rtdev=device
140 Use an external log (metadata journal)
141 An XFS filesystem has up to three part
142 section, and a real-time section. The
143 optional, and the log section can be s
144 section or contained within it.
145
146 noalign
147 Data allocations will not be aligned a
148 boundaries. This is only relevant to f
149 with non-zero data alignment parameter
150 **mkfs(8)**.
151
152 norecovery
153 The filesystem will be mounted without
154 If the filesystem was not cleanly unmo
155 be inconsistent when mounted in ``nore
156 Some files or directories may not be a
157 Filesystems mounted ``norecovery`` mus
158 the mount will fail.
159
160 nouuid
161 Don't check for double mounted file sy
162 system ``uuid``. This is useful to mo
163 and often used in combination with ``n
164 read-only snapshots.
165
166 noquota
167 Forcibly turns off all quota accountin
168 within the filesystem.
169
170 uquota/usrquota/uqnoenforce/quota
171 User disk quota accounting enabled, an
172 enforced. Refer to **xfs_quota(8)** f
173
174 gquota/grpquota/gqnoenforce
175 Group disk quota accounting enabled an
176 enforced. Refer to **xfs_quota(8)** f
177
178 pquota/prjquota/pqnoenforce
179 Project disk quota accounting enabled
180 enforced. Refer to **xfs_quota(8)** f
181
182 sunit=value and swidth=value
183 Used to specify the stripe unit and wi
184 or a stripe volume. "value" must be s
185 block units. These options are only re
186 that were created with non-zero data a
187
188 The ``sunit`` and ``swidth`` parameter
189 with the existing filesystem alignment
190 general, that means the only valid cha
191 increasing it by a power-of-2 multiple
192 are any integer multiple of a valid ``
193
194 Typically the only time these mount op
195 after an underlying RAID device has ha
196 modified, such as adding a new disk to
197 reshaping it.
198
199 swalloc
200 Data allocations will be rounded up to
201 when the current end of file is being
202 size is larger than the stripe width s
203
204 wsync
205 When specified, all filesystem namespa
206 executed synchronously. This ensures t
207 operation (create, unlink, etc) comple
208 namespace is on stable storage. This i
209 where failover must not result in clie
210 inconsistent namespace presentation du
211 failover event.
212
213 Deprecation of V4 Format
214 ========================
215
216 The V4 filesystem format lacks certain feature
217 the V5 format, such as metadata checksumming,
218 verification, and the ability to store timesta
219 Because of this, the V4 format is deprecated.
220 by backing up their files, reformatting, and r
221
222 Administrators and users can detect a V4 files
223 against a filesystem mountpoint and checking f
224 "crc=". If no such string is found, please up
225 latest version and try again.
226
227 The deprecation will take place in two parts.
228 filesystems can now be disabled at kernel buil
229 The option will default to yes until September
230 will be changed to default to no. In Septembe
231 removed from the codebase entirely.
232
233 Note: Distributors may choose to withdraw V4 f
234 the dates listed above.
235
236 Deprecated Mount Options
237 ========================
238
239 ============================ ==============
240 Name Removal Schedu
241 ============================ ==============
242 Mounting with V4 filesystem September 2030
243 Mounting ascii-ci filesystem September 2030
244 ikeep/noikeep September 2025
245 attr2/noattr2 September 2025
246 ============================ ==============
247
248
249 Removed Mount Options
250 =====================
251
252 =========================== =======
253 Name Removed
254 =========================== =======
255 delaylog/nodelaylog v4.0
256 ihashsize v4.0
257 irixsgid v4.0
258 osyncisdsync/osyncisosync v4.0
259 barrier v4.19
260 nobarrier v4.19
261 =========================== =======
262
263 sysctls
264 =======
265
266 The following sysctls are available for the XF
267
268 fs.xfs.stats_clear (Min: 0 Defau
269 Setting this to "1" clears accumulated
270 in /proc/fs/xfs/stat. It then immedia
271
272 fs.xfs.xfssyncd_centisecs (Min: 100 Def
273 The interval at which the filesystem f
274 out to disk and runs internal cache cl
275
276 fs.xfs.filestream_centisecs (Min: 1 Defau
277 The interval at which the filesystem a
278 references and returns timed-out AGs b
279 pool.
280
281 fs.xfs.speculative_prealloc_lifetime
282 (Units: seconds Min: 1 Default: 300
283 The interval at which the background s
284 with unused speculative preallocation
285 removes unused preallocation from clea
286 the unused space back to the free pool
287
288 fs.xfs.speculative_cow_prealloc_lifetime
289 This is an alias for speculative_preal
290
291 fs.xfs.error_level (Min: 0 Defau
292 A volume knob for error reporting when
293 This will generate detailed messages &
294 shutdowns, for example. Current thres
295
296 XFS_ERRLEVEL_OFF: 0
297 XFS_ERRLEVEL_LOW: 1
298 XFS_ERRLEVEL_HIGH: 5
299
300 fs.xfs.panic_mask (Min: 0 Defau
301 Causes certain error conditions to cal
302 OR together the tags which represent e
303
304 XFS_NO_PTAG
305 XFS_PTAG_IFLUSH
306 XFS_PTAG_LOGRES
307 XFS_PTAG_AILDELETE
308 XFS_PTAG_ERROR_REPORT
309 XFS_PTAG_SHUTDOWN_CORRUPT
310 XFS_PTAG_SHUTDOWN_IOERROR
311 XFS_PTAG_SHUTDOWN_LOGERROR
312 XFS_PTAG_FSBLOCK_ZERO
313 XFS_PTAG_VERIFIER_ERROR
314
315 This option is intended for debugging
316
317 fs.xfs.irix_symlink_mode (Min: 0 Defau
318 Controls whether symlinks are created
319 or whether their mode is affected by t
320
321 fs.xfs.irix_sgid_inherit (Min: 0 Defau
322 Controls files created in SGID directo
323 If the group ID of the new file does n
324 ID or one of the supplementary group I
325 ISGID bit is cleared if the irix_sgid_
326 is set.
327
328 fs.xfs.inherit_sync (Min: 0 Defau
329 Setting this to "1" will cause the "sy
330 by the **xfs_io(8)** chattr command on
331 inherited by files in that directory.
332
333 fs.xfs.inherit_nodump (Min: 0 Defau
334 Setting this to "1" will cause the "no
335 by the **xfs_io(8)** chattr command on
336 inherited by files in that directory.
337
338 fs.xfs.inherit_noatime (Min: 0 Defau
339 Setting this to "1" will cause the "no
340 by the **xfs_io(8)** chattr command on
341 inherited by files in that directory.
342
343 fs.xfs.inherit_nosymlinks (Min: 0 Defau
344 Setting this to "1" will cause the "no
345 by the **xfs_io(8)** chattr command on
346 inherited by files in that directory.
347
348 fs.xfs.inherit_nodefrag (Min: 0 Defau
349 Setting this to "1" will cause the "no
350 by the **xfs_io(8)** chattr command on
351 inherited by files in that directory.
352
353 fs.xfs.rotorstep (Min: 1 Defau
354 In "inode32" allocation mode, this opt
355 files the allocator attempts to alloca
356 group before moving to the next alloca
357 is to control the rate at which the al
358 allocation groups when allocating exte
359
360 Deprecated Sysctls
361 ==================
362
363 ===========================================
364 Name
365 ===========================================
366 fs.xfs.irix_sgid_inherit
367 fs.xfs.irix_symlink_mode
368 fs.xfs.speculative_cow_prealloc_lifetime
369 ===========================================
370
371
372 Removed Sysctls
373 ===============
374
375 ============================= =======
376 Name Removed
377 ============================= =======
378 fs.xfs.xfsbufd_centisec v4.0
379 fs.xfs.age_buffer_centisecs v4.0
380 ============================= =======
381
382 Error handling
383 ==============
384
385 XFS can act differently according to the type
386 operation. The implementation introduces the f
387 handler:
388
389 -failure speed:
390 Defines how fast XFS should propagate
391 error is found during the filesystem o
392 immediately, after a defined number of
393 or simply retry forever.
394
395 -error classes:
396 Specifies the subsystem the error conf
397 metadata IO or memory allocation. Diff
398 different error handlers for which beh
399
400 -error handlers:
401 Defines the behavior for a specific er
402
403 The filesystem behavior during an error can be
404 error handler works independently - the first
405 for a specific class will cause the error to b
406 retried.
407
408 The action taken by the filesystem when the er
409 dependent - it may cause a shut down in the ca
410 it may be reported back to userspace, or it ma
411 there's nothing useful we can with the error o
412 during unmount).
413
414 The configuration files are organized into the
415 mounted filesystem:
416
417 /sys/fs/xfs/<dev>/error/<class>/<error>/
418
419 Where:
420 <dev>
421 The short device name of the mounted f
422 name that shows up in XFS kernel error
423
424 <class>
425 The subsystem the error configuration
426 classes are:
427
428 - "metadata": applies metadata
429
430 <error>
431 The individual error handler configura
432
433
434 Each filesystem has "global" error configurati
435 level directory:
436
437 /sys/fs/xfs/<dev>/error/
438
439 fail_at_unmount (Min: 0 Defa
440 Defines the filesystem error behavior
441
442 If set to a value of 1, XFS will overr
443 during unmount and replace them with "
444 i.e. no retries, no retry timeout. Thi
445 succeed when there are persistent erro
446
447 If set to 0, the configured retry beha
448 retries and/or timeouts have been exha
449 completion when there are persistent e
450 filesystem from ever unmounting fully
451 handler configurations.
452
453 Note: there is no guarantee that fail_
454 unmount is in progress. It is possible
455 removed by the unmounting filesystem b
456 handler configuration causes unmount t
457 must be configured appropriately befor
458 unmount hangs.
459
460 Each filesystem has specific error class handl
461 propagation behaviour for specific errors. The
462 handler defined, which defines the behaviour f
463 specific handlers defined. Where multiple retr
464 a single error, the first retry configuration
465 to be propagated. The handler configurations a
466
467 /sys/fs/xfs/<dev>/error/<class>/<error>/
468
469 max_retries (Min: -1 Defa
470 Defines the allowed number of retries
471 the filesystem will propagate the erro
472 error context (e.g. a specific metadat
473 there is a successful completion of th
474
475 Setting the value to "-1" will cause X
476 specific error.
477
478 Setting the value to "0" will cause XF
479 specific error is reported.
480
481 Setting the value to "N" (where 0 < N
482 operation "N" times before propagating
483
484 retry_timeout_seconds (Min: -1 Def
485 Define the amount of time (in seconds)
486 allowed to retry its operations when t
487 found.
488
489 Setting the value to "-1" will allow X
490 specific error.
491
492 Setting the value to "0" will cause XF
493 specific error is reported.
494
495 Setting the value to "N" (where 0 < N
496 operation for up to "N" seconds before
497
498 **Note:** The default behaviour for a specific
499 the class and error context. For example, the
500 "metadata/ENODEV" are "0" rather than "-1" so
501 to "fail immediately" behaviour. This is done
502 unrecoverable error no matter how many times t
503
504 Workqueue Concurrency
505 =====================
506
507 XFS uses kernel workqueues to parallelize meta
508 enables it to take advantage of storage hardwa
509 operations simultaneously. This interface exp
510 details of XFS, and as such is explicitly not
511 guarantee the kernel may give userspace. Thes
512 the generic workqueue implementation XFS uses
513 provided here purely for diagnostic and tuning
514 time in the future.
515
516 The control knobs for a filesystem's workqueue
517 and the short name of the data device. They a
518
519 /sys/bus/workqueue/devices/${task}!${device}
520
521 ================ ===========
522 Task Description
523 ================ ===========
524 xfs_iwalk-$pid Inode scans of the entire fi
525 mount time quotacheck.
526 xfs-gc Background garbage collectio
527 speculatively allocated beyo
528 write operations.
529 ================ ===========
530
531 For example, the knobs for the quotacheck work
532 found in /sys/bus/workqueue/devices/xfs_iwalk-
533
534 The interesting knobs for XFS workqueues are a
535
536 ============ ===========
537 Knob Description
538 ============ ===========
539 max_active Maximum number of background
540 run the work.
541 cpumask CPUs upon which the threads a
542 nice Relative priority of scheduli
543 same nice levels that can be
544 ============ ===========
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.