Debian Codegraph @

upstream/debian-unstable/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 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).