LFS-MIGRATE(1)

NAME
lfs-migrate - migrate files or directories between MDTs or OSTs.

SYNOPSIS
lfs migrate [-h] [-v] [SETSTRIPE_OPTIONS ... ] FILE ...
lfs migrate -m START_MDT_INDEX [-cdHv] DIRECTORY

DESCRIPTION
Migrate OST objects between OSTs for the specified FILE, or recursively migrate DIRECTORY and all inodes/directories therein between MDTs.

OST MIGRATE OPTIONS

The lfs migrate command can be used for moving files from one (or more) OSTs to other OSTs (e.g. for space balancing between OSTs, or to evacuate an OST for hardware reasons), to change the stripe count or other layout parameters of a file (e.g. to increase the bandwidth of a file by striping it over multiple OSTs), or to move the file between different classes of storage (e.g. SSD vs. HDD OSTs, or local vs. remote OSTs in different pools).

In OST object migration mode, the command supports the same SETSTRIPE_OPTIONS listed in lfs-setstripe(1) to specify the layout of the target file. The migrate command differs from lfs setstripe in that lfs migrate will copy the data from the existing file(s) using the new layout parameters to the new OST(s). In contrast, lfs setstripe is used for creating new (empty) files with the specified layout. For OST object migration, there additional options available:

-b,--block
    Block access to the file by other applications during data migration (default). This prevents other processes from accessing the file during migration, which prevents data data writes to the old file objects from being lost. This should be used if an OST needs to be completely emptied prior to its removal, to ensure all requested files are migrated off the OST.

-h,--help
    Print usage message.

-n,--non-block
    Abort migration if concurrent file access is detected. This can be used with OST space balancing migration to avoid interfering with file access by applications if there is not a requirement to migrate any particular file to the new layout.

-D,--non-direct
    Do not use O_DIRECT read and write operations when migrating a file. The O_DIRECT option avoids data copy from kernel buffers into userspace, which can impose CPU and memory overhead on the copy operation, but makes read and write operations synchronous. Using the --non-direct option uses buffered read/write operations, which may improve migration speed at the cost of more CPU and memory overhead.
    This option cannot be used on encrypted files when the encryption key is not available. It will result in -ENOKEY.

-W,--bandwidth
    Limit how much file system bandwidth a migrate job can consume.

--stats
    Output verbose stats about migrate job progress in YAML format.

--stats-interval
    Controls how often the stats are output; this defaults to 5 seconds.

-v,--verbose
    Print each filename as it is migrated.

NOTE: lfs migrate has a complementary lfs_migrate script which is used to provide extra functionality when migrating file data between OSTs and has a separate man page. See lfs_migrate(1) for details.

MDT MIGRATE OPTIONS

-m,--mdt-index=MDT_INDEX[,MDT_INDEX,...]
    The specified DIRECTORY and all subdirectories and inodes will be migrated to the MDT with the specified MDT_INDEX. This is useful if new MDTs have been added to a filesystem and existing user or project directories should be migrated off old MDTs to balance the space usage and future metadata workload. If MDT_INDEX is -1, the MDT index will be balanced by free space and inodes among available MDTs. If multiple MDT_INDEX values are specified in a comma-seperated list, then all subdirectories will be striped across all of the specified MDT indices as if an equivalent -cN option were given.

-c,--mdt-count=COUNT
    All directories and subdirectories in the tree will be striped across COUNT MDTs, always using MDT_INDEX as the primary MDT for the directory. If MDT_INDEX is -1 then COUNT directory stripes will be chosen from MDTs proportional to the amount of free inodes and space on each MDT. If multiple MDT_INDEX values are specified in a comma-separated list, then the number of specified MDT_INDEX values must match COUNT.

-d,--directory
    Only migrate the specified DIRECTORY and the non-directory inodes that are directly located within it. Similar to 'ls -d' and 'lfs getstripe -d'.

-H,--mdt-hash=HASH_TYPE
    Use HASH_TYPE for the new directory layout.

    all_char (type 1)
        Sum of ASCII characters modulo number of MDTs. This provides weak hashing of the filename, and is suitable for only testing or when the input is known to have perfectly uniform distribution (e.g. sequential numbers).

    fnv_1a_64 (type 2)
        Fowler-Noll-Vo (FNV-1a) hash algorithm. This provides reasonably uniform, but not cryptographically strong, hashing of the filename. (default)

    crush (type 3)
        CRUSH hash algorithm. This is a consistent hash algorithm, so minimum sub files need to relocate during directory restripe.

NOTE
    Only the root user can migrate directories. Files that have been archived by HSM or are currently opened will fail to migrate, user can run the same migrate command again to finish migration when files are ready. Both inode and directory entry will be migrated. During migration directory and sub files can be accessed like normal ones, but the migration itself cannot be interrupted.

NOTE
    It is not currently possible to migrate files with an mdt component (Data-on-MDT, DoM). If it is necessary to migrate such files off a particular MDT, they must first be migrated to have a non-DoM file layout and then the inodes migrated separately. See EXAMPLES for details on how to migrate DoM files between MDTs.

WARNING
    Each migrated file or directory will have a new FID, and hence a new inode number. As a consequence, files archived by Lustre HSM that depend on the FID as the identifier in the HSM archive cannot currently be migrated. Having a new inode number may also cause backup tools to consider the migrated file(s) to be a new, and cause them to be backed up again.

EXAMPLES

$ lfs migrate -c 2 /mnt/lustre/file1
    This migrates the data in file1 into a new layout with 2 stripes.

$ lfs migrate -E 256M -c 1 -E 16G -c 4 -E eof -c 40 /mnt/lustre/file2
    This migrates the data in file2 into a three component composite layout (number of stripes depends on file size).

# lfs migrate -m 0,2 testremote
    Recursively move the subdirectories and inodes contained in directory remotedir from its current MDT to MDT0000 and MDT0002. The testremote directory and all of its subdirectories will be striped across both MDTs.

$ lfs migrate -m 0,2 -d ./testremote
    Move ./testremote and the first level of sub files from their current MDT to the MDT with index 0 and 2. Different from above case, the layout of subdirectories under ./testremote won't be changed.

# lfs setstripe -E 256M -c 1 -E 16G -c 4 -E eof -c 40 topdir
    Set a default PFL layout (without any DoM component) on the directory topdir,

# lfs find dir -type f -L mdt -0 | xargs -0 lfs migrate --copy topdir
    then find and migrate all regular files that have an mdt component to copy the default layout from the specified topdir,

# lfs migrate -m 2 topdir
    and finally migrate the directory topdir and all files and subdirectories in that tree to MDT0002. This allows migrating files with DoM components off an MDT.

AUTHOR
The lfs command is part of the Lustre filesystem.

SEE ALSO
lfs(1), lfs-setstripe(1), lfs-setdirstripe(1), lfs-getdirstripe(1), lfs-mkdir(1), lfs_migrate(1), lctl(8),