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