- <para>The <literal>lfs_migrate</literal> utility is a simple tool to assist migration of files between Lustre OSTs. The utility copies each specified file to a new file, verifies the file contents have not changed, and then renames the new file to the original filename. This allows balanced space usage between OSTs, moving files of OSTs that are starting to show hardware problems (though are still functional) or OSTs that will be discontinued.</para>
- <para>Because <literal>lfs_migrate</literal> is not closely integrated with the MDS, it cannot determine whether a file is currently open and/or in-use by other applications or nodes. This 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 results in the old file becoming an open-unlinked file and any modifications to that file are lost.</para>
- <para>Files to be migrated can be specified as command-line arguments. If a directory is specified on the command-line then all files within the directory are migrated. If no files are specified on the command-line, then a list of files is read from the standard input, making <literal>lfs_migrate</literal> suitable for use with <literal>lfs</literal> find to locate files on specific OSTs and/or matching other file attributes.</para>
- <para>The current file allocation policies on the MDS dictate where the new files are placed, taking into account whether specific OSTs have been disabled on the MDS via <literal>lctl</literal> (preventing new files from being allocated there), whether some OSTs are overly full (reducing the number of files placed on those OSTs), or if there is a specific default file striping for the target directory (potentially changing the stripe count, stripe size, OST pool, or OST index of a new file).</para>
- </section>
- <section remap="h5">
- <title>Options</title>
- <para>Options supporting <literal>lfs_migrate</literal> are described below.</para>
- <informaltable frame="all">
- <tgroup cols="2">
- <colspec colname="c1" colwidth="50*"/>
- <colspec colname="c2" colwidth="50*"/>
- <thead>
- <row>
- <entry>
- <para><emphasis role="bold">Option</emphasis></para>
- </entry>
- <entry>
- <para><emphasis role="bold">Description</emphasis></para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para> <literal>-c</literal></para>
- </entry>
- <entry>
- <para>Compares file data after migrate (default value, use <literal>-s</literal> to disable).</para>
- </entry>
- </row>
- <row>
- <entry>
- <para> <literal>-s</literal></para>
- </entry>
- <entry>
- <para>Skips file data comparison after migrate (use <literal>-c</literal> to enable).</para>
- </entry>
- </row>
- <row>
- <entry>
- <para> <literal>-h</literal></para>
- </entry>
- <entry>
- <para>Displays help information.</para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>-l</literal>
- </entry>
- <entry>
- <para>Migrates files with hard links (skips, by default). Files with multiple hard links are split into multiple separate files by <literal>lfs_migrate</literal>, so they are skipped, by default, to avoid breaking the hard links.</para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>-n</literal>
- </entry>
- <entry>
- <para>Only prints the names of files to be migrated.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para> <literal>-q</literal></para>
- </entry>
- <entry>
- <para>Runs quietly (does not print filenames or status).</para>
- </entry>
- </row>
- <row>
- <entry>
- <para> <literal>--y</literal></para>
- </entry>
- <entry>
- <para>Answers '<literal>y</literal>' to usage warning without prompting (for scripts).</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section remap="h5">
- <title>Examples</title>
- <para>Rebalances all files in <literal>/mnt/lustre/dir</literal>.</para>
- <screen>$ lfs_migrate /mnt/lustre/file</screen>
- <para>Migrates files in /test filesystem on OST004 larger than 4 GB in size.</para>
- <screen>$ lfs find /test -obd test-OST004 -size +4G | lfs_migrate -y</screen>
- </section>
- <section remap="h5">
- <title>See Also</title>
- <para><xref linkend="dbdoclet.50438206_94597"/></para>
- </section>
- </section>
- <section xml:id="dbdoclet.50438206_91700">
- <title><indexterm><primary>lfsck</primary></indexterm>
- <literal>lfsck</literal>
- </title>
- <para><literal>lfsck</literal> ensures that objects are not referenced by multiple MDS files, that there are no orphan objects on the OSTs (objects that do not have any file on the MDS which references them), and that all of the objects referenced by the MDS exist. Under normal circumstances, Lustre maintains such coherency by distributed logging mechanisms, but under exceptional circumstances that may fail (e.g. disk failure, file system corruption leading to e2fsck repair). To avoid lengthy downtime, you can also run <literal>lfsck</literal> once Lustre is already started.</para>
- <para>The <literal>e2fsck</literal> utility is run on each of the local MDS and OST device file systems and verifies that the underlying <literal>ldiskfs</literal> is consistent. After <literal>e2fsck</literal> is run, <literal>lfsck</literal> does distributed coherency checking for the Lustre file system. In most cases, <literal>e2fsck</literal> is sufficient to repair any file system issues and <literal>lfsck</literal> is not required.</para>
- <section remap="h5">
- <title>Synopsis</title>
- <screen>lfsck [-c|--create] [-d|--delete] [-f|--force] [-h|--help] [-l|--lostfound] [-n|--nofix] [-v|--verbose] --mdsdb mds_database_file --ostdb ost1_database_file [ost2_database_file...] <filesystem>
-</screen>
+ <para>The
+ <literal>lfs_migrate</literal> utility is a tool to assist migration
+ of file data between Lustre OSTs. The utility copies each specified
+ file to a temporary file using supplied <literal>lfs setstripe</literal>
+ options, if any, optionally verifies the file contents have not changed,
+ and then swaps the layout (OST objects) from the temporary file and the
+ original file (for Lustre 2.5 and later), or renames the temporary file
+ to the original filename. This allows the user/administrator to balance
+ space usage between OSTs, or move files off OSTs that are starting to show
+ hardware problems (though are still functional) or will be removed.</para>
+ <warning>
+ <para>For versions of Lustre before 2.5,
+ <literal>lfs_migrate</literal> was not integrated with the MDS at all.
+ That made it UNSAFE for use on files that were being modified by other
+ applications, since the file was migrated through a copy and rename of
+ the file. With Lustre 2.5 and later, the new file layout is swapped
+ with the existing file layout, which ensures that the user-visible
+ inode number is kept, and open file handles and locks on the file are
+ kept.</para>
+ </warning>
+ <para>Files to be migrated can be specified as command-line arguments. If
+ a directory is specified on the command-line then all files within the
+ directory are migrated. If no files are specified on the command-line,
+ then a list of files is read from the standard input, making
+ <literal>lfs_migrate</literal> suitable for use with
+ <literal>lfs find</literal> to locate files on specific OSTs and/or
+ matching other file attributes, and other tools that generate a list
+ of files on standard output.</para>
+ <para>Unless otherwise specified through command-line options, the
+ file allocation policies on the MDS dictate where the new files
+ are placed, taking into account whether specific OSTs have been
+ disabled on the MDS via <literal>lctl</literal> (preventing new
+ files from being allocated there), whether some OSTs are overly full
+ (reducing the number of files placed on those OSTs), or if there is
+ a specific default file striping for the parent directory (potentially
+ changing the stripe count, stripe size, OST pool, or OST index of a
+ new file).</para>