xfs_copy(8)

🎀 NAME 🎀

okay so the manual page is xfs_copy(8) and it's all about this: xfs_copy - copy the contents of an XFS filesystem 💖

🧚 SYNOPSIS 🧚

xfs_copy [ -bd ] [ -L log ] source target1 [ target2 ... ]
xfs_copy -V

✨ DESCRIPTION ✨

okay so xfs_copy copies an XFS filesystem to one or more targets in parallel 🔥 (see xfs(5)). The first one, the source argument, has to be the pathname of the device or file that holds the XFS filesystem. Everything after that is one or more target devices or file names. If your targets are devices, you get a copy of the source XFS filesystem on each one 💅. A target can also be a regular file, and then you get an image of the source filesystem saved inside that file 🦋. If the file doesn't exist yet, xfs_copy makes it for you 🫶.

The file ends up the same size as the source filesystem, but here's the lowkey magic 🪄: if the file lives on an XFS filesystem, it only eats roughly the space the source filesystem and its XFS log actually use. Why? xfs_copy seeks over the free blocks instead of copying them, and XFS handles sparse files really efficiently. It's giving space saver energy 🌈.

⚠️ bestie, only copy the right kinds of filesystems! xfs_copy should only be used on unmounted filesystems, read-only mounted filesystems, or frozen filesystems (see xfs_freeze(8)). Otherwise the copies come out inconsistent or corrupt 💀.

xfs_copy never touches the source filesystem, not even a little 🙈. Every new target is identical to the original except that each one gets a brand new unique filesystem identifier (UUID). So if the old and new filesystems are going to be used as separate, distinct filesystems, you should make the copies with xfs_copy or xfsdump(8)/xfsrestore(8) instead of dd(1) or other block-by-block disk copying programs 👑.

xfs_copy uses synchronous writes so write errors actually get caught 🔍.

It also uses pthreads(7) for simultaneous parallel writes 🧵. It spins up one extra thread for each target it's writing to, and all of those threads die if xfs_copy terminates or aborts 💜.

💅 OPTIONS 💅

• -d — makes a duplicate, true clone filesystem 👯. Only do this if the new filesystem is going to replace the original, like when you're swapping out a disk 🔄.
• -b — the buffered option 🧸. It makes sure direct IO isn't attempted on any of the target files, which is clutch when the filesystem holding the target doesn't support direct IO.
• -L log — tells xfs_copy where to put its log file, if you don't want the default /var/tmp/xfs_copy.log.XXXXXX 📝.
• -V — prints the version number and then bounces 👋.

🔮 DIAGNOSTICS 🔮

xfs_copy reports errors to both stderr and a more detailed log file 📜. That log is named like /var/tmp/xfs_copy.log.XXXXXX, or it's whatever you picked with the -L option.

If xfs_copy hits a write error on a target, that one copy gets aborted 🙅‍♀️. An error message goes to both stderr and the log file, but the rest of the copies keep going, no drama 🌸. When xfs_copy finally terminates, it reports all the aborted targets to both stderr and the log file again 📣.

If all targets abort, or if there's an error reading the source filesystem, xfs_copy immediately aborts 😭.

The exit code is 0 if every target copied successfully, and 1 if any target failed 🥹.

🍓 NOTES 🍓

ngl this one is important 🫠. When you're moving a filesystem from one disk to another, and the original is way smaller than the new disk so you're going to grow it, we recommend using mkfs.xfs(8) and xfsdump(8)/xfsrestore(8) instead of xfs_copy and xfs_growfs(8) 🙏. The layout you get from xfs_copy/xfs_growfs is almost always worse than what mkfs.xfs/xfsdump/xfsrestore gives you. For small filesystems, that difference can really hurt performance 🐌. This comes from the way xfs_growfs(8) works, not from any shortcoming in xfs_copy itself 💁‍♀️.

🚫 CAVEATS 🚫

xfs_copy can't copy XFS filesystems that have a real-time section, or XFS filesystems with external logs 🙅. In both cases it aborts with an error message, so don't be surprised 😤.

🦋 SEE ALSO 🦋

mkfs.xfs(8), xfsdump(8), xfsrestore(8), xfs_freeze(8), xfs_growfs(8), xfs(5). go read those, they're iconic 💖

ok that's the whole xfs_copy(8) page, from the System Manager's Manual, all tea spilled 🫶✨ periodt 💅🌈