man/man5/xfs.5

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