From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.

The XFS filesystem is a high-performance journaling filesystem. It is ACL (POSIX) compliant for use with Linux.

XFS has a particularly strong reputation for reliability and led to the creation of the venerable xfstests Linux kernel test suite which now tests regressions in various filesystems.



KERNEL Enable XFS support (CONFIG_XFS_FS:)
File systems  --->
   <*> XFS filesystem support


KERNEL Enable optional XFS features
File systems  --->
   [*]   XFS Quota support
   [*]   XFS POSIX ACL support
   [*]   XFS Realtime subvolume support
   [ ]   XFS Verbose Warnings
   [ ]   XFS Debugging support
   [ ]   XFS online metadata check support
      [ ]   XFS online metadata check usage data collection
      [ ]   XFS online metadata repair support


The sys-fs/xfsprogs package is needed for XFS userspace utilities:

root #emerge --ask sys-fs/xfsprogs



Mount XFS filesystems with the mount command.

XFS supports SSD discards in /etc/fstab.


Make an XFS filesystem with mkfs.xfs from xfsprogs:

root #mkfs.xfs -L 'label'

The label is optional. Further tuning on creation might be interesting for use as a RAID, multi-terabyte drives, and doing the journaling for a HDD on a separate SSD.

Filesystem information

xfs_spaceman can be used to display information about the space available and to run a report on the health of a filesystem.

root #xfs_spaceman -c info /path/to/mountpoint

Changing parameters

It is not possible to change the parameters of a mounted filesystem

The parameters of an XFS filesystem can be changed using xfs_admin. For the full list of options, view the manpage: xfs_admin(8)

root #xfs_admin -L 'label' /dev/sda1

Expanding a filesystem

The filesystem must be mounted to be grown

To grow an XFS filesystem to N amount, use xfs_growfs.

root #xfs_growfs -D N /path/to/mountpoint
Using the -d argument results in it being expanded to the max size


To suspend access to a filesystem, use the xfs_freeze command.

root #xfs_freeze -f /path/to/mountpoint


Utility Description[1] Man page
fsck.xfs Checks a filesystem for corruption fsck.xfs(8)
mkfs.xfs Creates a new filesystem mkfs.xfs(8)
xfs_admin Changes the parameters of a filesystem xfs_admin(8)
xfs_bmap Prints block mapping for an XFS file xfs_bmap(8)
xfs_copy Copies contents of a filesystem to one or more targets in parallel xfs_copy(8)
xfs_estimate Estimate the amount of space a directory would consume if it were copied to an XFS filesystem xfs_estimate(8)
xfs_db Used to debug an XFS filesystem xfs_db(8)
xfs_freeze Suspends access to a filesystem xfs_freeze(8)
xfs_fsr Improves organization of mounted filesystems, compacting or improving the layout of extents xfs_fsr(8)
xfs_growfs Increases a filesystem's size xfs_growfs(8)
xfs_info Equivalent to invoking xfs_growfs but does not change any aspects about the filesystem xfs_info(8)
xfs_io Used for debugging, like xfs_db but for regular file paths than raw volumes xfs_io(8)
xfs_logprint Prints the log of an XFS filesystem xfs_logprint(8)
xfs_mdrestore Restores an XFS metadump image to a filesystem image xfs_mdrestore(8)
xfs_metadump Copies filesystem metadata to a file xfs_metadump(8)
xfs_mkfile Creates an XFS file (padded by zeroes by default) xfs_mkfile(8)
xfs_ncheck Generates pathnames from inode numbers xfs_ncheck(8)
xfs_quota Used for reporting and editing different aspects of filesystem quotas xfs_quota(8)
xfs_repair Repairs corrupted or damaged XFS filesystems xfs_repair(8)
xfs_rtcp Copies a file to a real-time partition xfs_rtcp(8)
xfs_scrub Checks and repairs contents of a mounted filesystem xfs_scrub(8)
xfs_scrub_all Scrubs all mounted XFS filesystems xfs_scrub_all(8)
xfs_spaceman Reports and controls free space usage xfs_spaceman(8)


Year 2038 timestamp support (bigtime)

Older partitions (created with <xfsprogs-5.15) will not have bigtime enabled by default. Mounting such partitions results in a warning like:

root #dmesg
[    4.036258] xfs filesystem being mounted at /home supports timestamps until 2038 (0x7fffffff)

To check the current version of xfsprogs, run mkfs.xfs -V. There's no need for this on up-to-date Gentoo systems, but it might be necessary if using install media from another distribution with older userland.

The bigtime code support was enabled by default in xfsprogs 5.15, so manual setting is not required in newer versions.

Beginning with kernel 5.10, XFS gained bigtime support to extend the maximum recorded date stamps from 2038 to 2486 for the V5 on-disk format.[2]

To upgrade an older filesystem to bigtime, first cleanly unmount the file system. The upgrade will refuse to run if the unmount was not completely clean.

Then run:

root #xfs_admin -O bigtime=1 /dev/sda1

Replacing /dev/sda1 with the device path.

XFS on the root mount will require an initramfs or other live environment with the necessary tools to perform an upgrade to the metadata.

Using Dracut initramfs to perform the upgrade

First, Dracut needs additional files included in the initramfs in order to perform the upgrade. This can be accomplished with either the --install option or inside a configuration file using the install_items option.

root #dracut --install "/usr/sbin/xfs_admin /usr/bin/expr" ...

Then, the kernel command line option can be modified to include rd.break=pre-mount to stop the initramfs just before it would mount the root filesystem. Ensure this is done temporarily and removed on subsequent reboots after upgrade.


To schedule removal at the next run:

root #emerge --ask --depclean --verbose sys-fs/xfsprogs

See also

  • Deduplication — uses the clone mechanism of a copy-on-write or CoW capable filesystem, a feature that allows to share data of copied but identical files
  • FATfilesystem originally created for use with MS-DOS (and later pre-NT Microsoft Windows).
  • Ext4 — an open source disk filesystem and most recent version of the extended series of filesystems.
  • Btrfs — a copy-on-write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, self-healing properties, and easy administration.