LFS_MIGRATE(1)

📦 version 2.17.58, in ubuntu stonking

💅 LFS_MIGRATE 💅

hi bestie 🫶 welcome to LFS_MIGRATE(1), one of the Lustre User Utilities. (yes it's a man page, yes the manual name is baked in at the top, don't worry, we already hugged it hello.)

🌸 NAME 🌸

lfs_migrate — migrate files between Lustre OSTs

✨ SYNOPSIS ✨

lfs_migrate [-A [-C CAP] [-M MIN_FREE] [-X MAX_FREE ]] [--cp] [--dry-
            run|-n] [--fid|-F [--lustre-dir LUSTRE_MOUNT_POINT]]
            [--help|-h] [--no-rsync|--rsync] [--pool|-p POOL]
            [--quiet|-q] [--restripe|-R] [--stripe-count|-c
            STRIPE_COUNT] [--stripe-size|-S STRIPE_SIZE ] [--skip|-s]
            [--verbose|-v] [--yes|-y] [-D] [-0] [FILE|FID|DIR]...

🦋 DESCRIPTION 🦋

🚨 WARNING: lfs_migrate is scheduled for removal after Lustre 2.20. Please use lfs-migrate(1) instead. no cap, it's getting sunset, so start moving your habits over 💀

okay so lfs_migrate is the lil helper that assists migration of files between Lustre OSTs, and it can also restripe the files while it's at it. the whole vibe is: it copies each specified file to a new file, verifies the file contents have not changed, and then replaces the original filename with the new file — and it does that either atomically via lfs-migrate(1) on Lustre 2.5 and later, or with mv(1) on older versions of Lustre. that's the glow-up 🎀

and why would you even do this? three iconic reasons, bestie:

  • balancing space usage between OSTs,
  • moving files off OSTs that are starting to show hardware problems but are still functional,
  • or moving off OSTs that will be removed from the filesystem.

Files to be migrated can be specified as command-line arguments. if you point it at a directory on the command-line, then all files within that directory are migrated. and if you specify no files on the command-line at all? then a list of files is read from the standard input — which makes lfs_migrate perfect for use with lfs-find(1) to locate files on specific OSTs and/or matching other file attributes, or honestly with any other tool that generates a list of files. chef's kiss 🧚

Any options and arguments not explicitly recognized by lfs_migrate are passed through to the underlying lfs migrate command — so peep lfs-migrate(1) and lfs-setstripe(1) for a complete list of options.

here's a subtle lore drop for backward compatibility: the -n option is used by the script to mean dry-run (no modifications made), and is not passed to lfs migrate as the non-block option. so if you actually want non-block, you have to use the long option --non-block. yes really. write it down 😭

final lore: the current file allocation policies on MDS dictate where the new files are placed. and that takes into account:

  • whether specific OSTs have been disabled on the MDS via lctl(8) (which prevents new files from being allocated there),
  • whether some OSTs are overly full (which reduces the number of files placed on those OSTs),
  • or whether there's a specific default file striping for the target directory — which can potentially change the stripe count, stripe size, OST pool, or OST index of a new file.

so it's giving main character MDS energy, and you're just along for the ride 👑

🔥 OPTIONS 🔥

one bullet per option, every single one, no skips, periodt ✨

  • --cp — Force use of cp(1) to copy files instead of rsync(1).
  • -n, --dry-run — Only print the names of files to be migrated. (nothing actually moves, it's just window shopping 🛍️)
  • -D — Do not use direct I/O to copy file contents.
  • -F, --fid — FID(s) are provided from command line/stdin instead of file path(s). Option --lustre-dir=LUSTRE_MOUNT_POINT may be specified at the same time.
  • --lustre-dir=LUSTRE_MOUNT_POINT — The mount point of Lustre file system on which FID(s) are when --fid is specified. If there is only one mounted Lustre file system, this option is not necessary. This option must be specified together with --fid (they're a package deal, don't separate them 💞).
  • -A — Automatically determine the stripe count for the file, using the algorithm count = sqrt(filesize_in_GB) + 1. This option may not be specified at the same time as the -c or -R options.
  • -c, --stripe-countSTRIPE_COUNT — Restripe file using the specified STRIPE_COUNT. This option may not be specified at the same time as the -A or -R options.
  • -C CAP — When -A is set, limit the migrated file to use on each OST at most 1/CAP of the available space of the smallest OST. If this option is not set, a default value of 100 is used, limiting the object size to 1% of available space.
  • -h, --help — Display usage message.
  • --no-rsync — Do not fall back to using rsync if lfs-migrate(1) fails. Cannot be used at the same time as --rsync.
  • -M, --min-freeMIN_FREE — When -A is set, only consider OSTs with free space greater than the MIN_FREE value to be available for migration. The value is specified in KB. If this option is not set, a default of 256MB is used.
  • -p, --poolPOOL — Migrate files to specified POOL.
  • -q, --quiet — Run quietly (don't print filenames or status). shhh 🤫
  • --rsync — Force rsync to be used instead of lfs-migrate(1). May not be used at the same time as --no-rsync.
  • -R, --restripe — Restripe file using default directory striping instead of keeping striping. This option may not be specified at the same time as the -A, -c, or -S options. (these options are passed through to lfs migrate, and are therefore not listed here).
  • -s, --skip — Skip file data comparison after migrate. Default is to compare migrated file against original to verify correctness. (skipping the vibe check, bold of you 🌈)
  • -S, --stripe-sizeSTRIPE_SIZE — Restripe file using the specified stripe size. This option may not be specified at the same time as the -R option.
  • -v, --verbose — Show verbose debug messages.
  • -X, --max-freeMAX_FREE — When -A is set, MAX_FREE is the maximum amount of free space that can be considered available for the migration of the file on each OST. The value is specified in KB. This option is useful for testing, by simulating OSTs that are nearly full.
  • -y, --yes — Answer 'y' to usage warning without prompt (--rsync only, use with caution). ⚠️ caution, bestie, this one skips the "u sure?" moment.
  • -0 — Input file names on stdin are separated by a null character.

🌈 NOTES 🌈

In versions prior to 2.5, lfs_migrate is not closely integrated with the MDS, and cannot determine whether a file is currently open and/or in-use by other applications or nodes.

💀 That makes it UNSAFE for use on files that might be modified by other applications, since the migrated file is only a copy of the current file. This will result in the old file becoming an open-unlinked file, and any modifications to that file will be lost.

like. genuinely lost. gone. not coming back. so don't do it on files that are being actively written, fr fr 🙈

🎀 EXAMPLES 🎀

To rebalance all files within /testfs/jobs/2011:

# lfs_migrate /testfs/jobs/2011

To migrate files within the /testfs filesystem on OST0004 (perhaps because it is much more full than other OSTs), larger than 4GB (because it is more efficient to migrate a few large files than many small ones), and older than two days (to avoid files that are in use) to use auto-restriping for these files, after disabling file creation on testfs-OST0004 (this is needed on all MDS nodes):

[   mds]# lctl set_param osp.testfs-OST0004*.max_create_count=0
[client]# lfs find /testfs -obd testfs-OST0004 -size +4G -mtime +2d | lfs_migrate -A
[   mds]# lctl set_param osp.testfs-OST0004*.max_create_count=20000

To use automatic restriping, and limit the object size per OST to 5% of current free space:

# lfs_migrate -A -C 20 /testfs/jobs/2011

⭐ AVAILABILITY ⭐

lfs_migrate is part of the lustre(7) filesystem package. Added in release 1.8.4. it's been around, it's a legacy icon 👑

👀 SEE ALSO 👀

and that's the whole page, bestie 💖 go forth and migrate responsibly. Lustre · 2025-12-20 · LFS_MIGRATE(1) 🦋 mwah 💅

📦 where this page comes from