XFS

Resources

Home

Wikipedia

Userspace

Kernel

Tests

xfs (on irc://irc.oftc.net)

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

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

Installation

Kernel

KERNEL Enable XFS support

 File systems  --->
  <*> XFS filesystem support Search for <code>CONFIG_XFS_FS</code> to find this item.

Optional:

KERNEL Enable optional XFS features

 File systems  --->
  <*> XFS filesystem support Search for <code>CONFIG_XFS_FS</code> to find this item.
    [*]   XFS Quota support Search for <code>CONFIG_XFS_QUOTA</code> to find this item.
    [*]   XFS POSIX ACL support Search for <code>CONFIG_XFS_POSIX_ACL</code> to find this item.
    [*]   XFS Realtime subvolume support Search for <code>CONFIG_XFS_RT</code> to find this item.
  [ ]   XFS Verbose Warnings
  [ ]   XFS Debugging support
  [ ]   XFS online metadata check support
     [ ]   XFS online metadata check usage data collection
     [ ]   XFS online metadata repair support

Emerge

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

root #emerge --ask sys-fs/xfsprogs

Usage

Mount

Mount XFS filesystems with the mount command.

Note
XFS supports SSD discards in /etc/fstab.

Creation

To make an XFS filesystem with mkfs.xfs from sys-fs/xfsprogs:

root #mkfs.xfs -L 'label' /dev/sda1

The label is optional. Further tuning on creation might be interesting for use as a RAID, multi-terabyte drives, and placing the journal 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

Important
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

Important
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

Note
Using the -d argument results in it being expanded to the max size

Freezing

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

root #xfs_freeze -f /path/to/mountpoint

Utilities

Utility	Description	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)

Maintenance

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.

bigtime 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.

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.

Note
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.

Removal

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
• FAT — filesystem originally created for use with MS-DOS (and later pre-NT Microsoft Windows).
• Ext4 — an open source disk filesystem and the 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.