b=22481 man page for lfs_migrate

Add a manual page for lfs_migrate.
Minor formatting changes of the lfs_migrate::usage() message.

diff --git a/lustre/doc/lfs_migrate.1 b/lustre/doc/lfs_migrate.1
new file mode 100644 (file)
index 0000000..bf65ebe
--- /dev/null
+++ b/lustre/doc/lfs_migrate.1
@@ -0,0 +1,111 @@
+.TH lfs_migrate 1 "Jul 21, 2010" Lustre "utilities"
+.SH NAME
+.Blfs_migrate
+\- simple tool to migrate files between Lustre OSTs
+.SH SYNOPSIS
+.B lfs_migrate
+.RB [ -c | -s ]
+.RB [ -h ]
+.RB [ -l ]
+.RB [ -n ]
+.RB [ -y ]
+.RI [ file | "directory ..." ]
+.br
+.SH DESCRIPTION
+.B lfs_migrate
+is a simple tool to assist migration of files between Lustre OSTs.  It
+is simply copying each specified file to a new file, verifying the file
+contents have not changed, and then renaming the new file back to the
+original filename.  This allows balancing space usage between OSTs, moving
+files of OSTs that are starting to show hardware problems (though are still
+functional), or OSTs will be discontinued.
+.PP
+Because
+.B lfs_migrate
+is
+.B not
+closely integrated with the MDS, it cannot determine whether a file
+is currently open and/or in-use by other applications or nodes.  That makes
+it
+.B
+UNSAFE
+for use on files that might be modified by other applications, since the
+migrated file is only a copy of the current file, and this will result in
+the old file becoming an open-unlinked file and any modifications to that
+file will be lost.
+.PP
+Files to be migrated can be specified as command-line arguments.  If a
+directory is specified on the command-line then all files within that
+directory are migrated.  If no files are specified on the command-line,
+then a list of files is read from the standard input, making
+.B lfs_migrate
+suitable for use with
+.BR lfs (1) " find"
+to locate files on specific OSTs and/or matching other file attributes.
+.PP
+The current file allocation policies on MDS dictate where the new files
+are placed, taking into account whether specific OSTs have been disabled
+on the MDS via
+.BR lctl (8)
+(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).
+.SH OPTIONS
+.TP
+.B \\-c
+Compare file data after migrate (default, use
+.B \\-s
+to disable).
+.TP
+.B \\-s
+skip file data comparison after migrate (use
+.B \\-c
+to enable).
+.TP
+.B \\-h
+Display help information.
+.TP
+.B \\-l
+Migrate files with hard links (skip by default).  Files with multiple
+hard links will be split into multiple separate files by
+.B lfs_migrate
+so they are skipped by default to avoid breaking the hard links.
+.TP
+.B \\-n
+Only print the names of files to be migrated
+.TP
+.B \\-q
+Run quietly (don't print filenames or status)
+.TP
+.B \\-y
+Answer 'y' to usage warning without prompting (for scripts)
+.SH EXAMPLES
+To rebalance all files within
+.IR /mnt/lustre/dir :
+.IP
+lfs_migrate /mnt/lustre/file
+.PP
+To migrate files within the
+.I /test
+filesystem on OST0004 larger than 4GB in size:
+.IP
+lfs find /test -obd test-OST0004 -size +4G | lfs_migrate -y
+.SH KNOWN BUGS
+Hard links could be handled correctly in Lustre 2.0 by using
+.BR lfs (1) " fid2path" .
+.PP
+Eventually, this functionality will be integrated into
+.BR lfs (1)
+itself and will integrate with the MDS layout locking to make it safe
+in the presence of opened files and ongoing file IO.
+.PP
+Please report all bugs to http://bugzilla.lustre.org/
+.SH AVAILABILITY
+.B lfs_migrate
+is part of the 
+.BR Lustre (7) 
+filesystem package.  Added in the 1.8.4 release.
+.SH SEE ALSO
+.BR lfs (1)

diff --git a/lustre/scripts/lfs_migrate b/lustre/scripts/lfs_migrate
index 776fbe6..7ec1051 100644 (file)
--- a/lustre/scripts/lfs_migrate
+++ b/lustre/scripts/lfs_migrate
@@ -19,17 +19,22 @@ ECHO=echo
 LFS=${LFS:-lfs}
 
 usage() {
-    echo "usage: lfs_migrate [-c|-s] [-h] [-l] [-n] [-y] [file|dir ...]" 1>&2
-    echo "    -c compare file data after migrate (default)" 1>&2
-    echo "    -s skip file data comparison after migrate" 1>&2
-    echo "    -h show this usage message" 1>&2
-    echo "    -l migrate files with hard links (skip by default)" 1>&2
-    echo "    -n only print the names of files to be migrated" 1>&2
-    echo "    -y answer 'y' to usage question" 1>&2
-    echo "    if no file or directory is given, file list is read from stdin"
-    echo ""
-    echo "e.g.: lfs_migrate -c /mnt/lustre/file"
-    echo "      lfs find /scratch -O lustre-OST0004 -size +4G | lfs_migrate -y"
+    cat -- <<USAGE 1>&2
+usage: lfs_migrate [-c|-s] [-h] [-l] [-n] [-y] [file|dir ...]
+    -c compare file data after migrate (default)
+    -s skip file data comparison after migrate
+    -h show this usage message
+    -l migrate files with hard links (skip by default)
+    -n only print the names of files to be migrated
+    -q run quietly (don't print filenames or status)
+    -y answer 'y' to usage question
+
+If a directory is an argument, all files in the directory are migrated.
+If no file/directory is given, the file list is read from standard input.
+
+e.g.: lfs_migrate /mnt/lustre/file
+      lfs find /test -O test-OST0004 -size +4G | lfs_migrate -y
+USAGE
     exit 1
 }