xfs_defrag(8)

NAME
xfs_defrag - A file defragmentation tool for XFS.

SYNOPSIS
xfs_defrag [ -f free_space ] [ -i idle_time ] [ -s segment_limit ] [ -v ] file

DESCRIPTION
xfs_defrag is applicable to files on an XFS file system with reflink feature enabled.

xfs_defrag performs defragmentation on a file. It allows IO requests to the file from other processes during the defragmentation process with possible extra delay. The IO delay caused by defragmentation can be tuned by the command line options. XFS provides another defragmentation tool named xfs_fsr. Where xfs_fsr works on the whole file by preallocating extents for the entire file and copying the source file contents to the preallocated blocks in the new file using the direct IO. xfs_fsr will block IO for other processes until the entire file is defragmented. Unlike xfs_fsr, xfs_defrag works on a segment of the file at a time and IO requests from other processes can be served between processing those segments. It uses the XFS buffered IO and the Copy on Write (CoW) kernel support to selectively unshare many smaller adjacent extents to a hopefully larger contiguous segment. After the data in the original blocks are written to storage in the new segment, all of the original unshared blocks are freed back to the file system but all of the original shared disk blocks remain allocated in the owning file(s). Therefore, the defragmented shared extents consume additional blocks and may fill up the XFS file system.

Options:

-f free_space
    The file system must contain at least free_space amount of free space measured in MiB to allow segments that contain shared extents to be defragmented. A value of 0 or a negative value disables this exclusion. The default value is 1024 MiB.

-i idle_time
    The specified time in milliseconds before defragmenting the next segment. A longer idle time will cause less impact on inflight IO but more defragmentation time. The default idle time is 250 ms.

-s segment_limit
    This specifies the upper limitation of segment size in MiB. A larger segment size generally gives a better defragmention speed and less fragmentation but can add longer maximum IO delay. Conversely, a smaller segment size reduces IO delay but results in more fragmentation. The minimium value is 1 MiB, the default value is 16 MiB.

-v  shows stats information after defragmentation.

EXAMPLE
# xfs_defrag /test_dir/test_file
Defragged 53 extents to 2 extents
Another example which shows stats:
# xfs_defrag -v /test_dir/test_file2
Extents scaned: 89, "unwritten": 0,"shared": 45
Tried to defragment 3 extents (16777216 bytes) in 1 segments
Time stats(ms): max clone: 0, max unshare: 34, max punch_hole: 0 Defragged 89 extents to 87 extents

RETURN VALUE
xfs_defrag returns an exit code of 0 on success or 1 if an error occured.

NOTES
File system space consumption
When defragmenting shared blocks consumes file system free blocks, to avoid consuming too many blocks, xfs_defrag will exclude sdefragmenting segments that contain shared blocks when the file system free space is below a threshold. See the -f option.

Safety and consistency
xfs_defrag uses the XFS CoW unshare feature and is guaranteed safe for SIGINT and a kernel crash.

Impact from extsize and cowextsize
The XFS extsize and cowextsize are size hints which can interfere with the segment size.
1) Small values: xfs_defrag expects the new blocks to be contigous. But a small non-zero hint causes more separated block allocations. That might descreases the effectiveness of the defragmentation process. And even results in a more fragmented file.
2) Large values: With large hints, each unsharing operation allocates more new blocks than the real segment size. When the unsharing operation completed, the extra new blocks will remain allocated for a while before they are reclaimed. Those remained blocks cause CoW when file writes come to them and could thus make the file more fragmented. We suggest value 0 for both size hints.

Recommendations
xfs_defrag runs best when there is only one defragmentation process per XFS file system at a time. It is also not recommended to run the defragmentation process on a XFS file system experiencing heavy data allocation.

File size consistency
The defragmenation process assumes the file size remains unchanged. xfs_defrag will report error if the file is truncated and will defragment the entire extented part as a single segment which could cause excessive delays to the IOs in the file.

SEE ALSO
xfs_fsr(8)