From acc0a56bde36937beef89e6e36be03c98c681485 Mon Sep 17 00:00:00 2001 From: Andreas Dilger Date: Thu, 5 Aug 2010 00:10:16 +0400 Subject: [PATCH] b=22481 man page for lfs_migrate Add a manual page for lfs_migrate. Minor formatting changes of the lfs_migrate::usage() message. --- lustre/doc/lfs_migrate.1 | 111 +++++++++++++++++++++++++++++++++++++++++++++ lustre/scripts/lfs_migrate | 27 ++++++----- 2 files changed, 127 insertions(+), 11 deletions(-) create mode 100644 lustre/doc/lfs_migrate.1 diff --git a/lustre/doc/lfs_migrate.1 b/lustre/doc/lfs_migrate.1 new file mode 100644 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 --- 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 -- <&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 } -- 1.8.3.1