X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lustre%2Fdoc%2Flfs_migrate.1;h=fc9ffabae3a436a131954d45226d3bd349fe3b84;hb=1be889a5bc713ab8db6c3d2cbf83aef8df813293;hp=c6f198a3db16f12e71a590d99579d5c38303aa53;hpb=94a34b9ad16e9dc2bbcc0ed7bad89f2e6a671a90;p=fs%2Flustre-release.git diff --git a/lustre/doc/lfs_migrate.1 b/lustre/doc/lfs_migrate.1 index c6f198a..fc9ffaba 100644 --- a/lustre/doc/lfs_migrate.1 +++ b/lustre/doc/lfs_migrate.1 @@ -1,41 +1,37 @@ -.TH lfs_migrate 1 "Jul 21, 2010" Lustre "utilities" +.TH lfs_migrate 1 "Dec 19, 2017" Lustre "utilities" .SH NAME .B lfs_migrate -\- simple tool to migrate files between Lustre OSTs +\- migrate files between Lustre OSTs .SH SYNOPSIS .B lfs_migrate -.RB [ -c ] -.RB [ -h ] -.RB [ -l ] -.RB [ -n ] -.RB [ -q ] -.RB [ -R ] -.RB [ -s ] -.RB [ -y ] -.RI [ file | "directory ..." ] +.RB [ "-A " [ -C \fI \fR] [ -M \fI \fR] [ -X \fI \fR]] +.RB [ --dry-run | -n ] +.RB [ --help | -h ] +.RB [ --no-rsync | --rsync ] +.RB [ --pool | -p \fI \fR] +.RB [ --quiet | -q ] +.RB [ --restripe | -R ] +.RB [ --stripe-count | -c \fI \fR] +.RB [ --stripe-size | -S \fI \fR] +.RB [ --skip | -s ] +.RB [ --verbose | -v ] +.RB [ --yes | -y ] +.RB [ -D ] +.RB [ -0 ] +.RI [ FILE | DIR ] ... .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 off OSTs that are starting to show hardware problems (though are still -functional), or OSTs that will be removed from the filesystem. -.PP -Because -.B lfs_migrate -is -.B not -yet 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. +is a tool to assist migration of files between Lustre OSTs, possibly also +restriping the files as it goes. 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 (either atomically via +.BR lfs-migrate (1) +on Lustre 2.5 and later, or +.BR mv (1) +on older versions of Lustre). This allows balancing space usage between OSTs, +moving files off OSTs that are starting to show hardware problems but are still +functional, or OSTs that will be removed from the filesystem. .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 @@ -43,8 +39,25 @@ 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. +.BR lfs-find (1) +to locate files on specific OSTs and/or matching other file attributes, +or any other tools that generate a list of files. +.PP +Any options and arguments not explicitly recognized by +.B lfs_migrate +are passed through to the underlying +.B lfs migrate +command, see +.BR lfs-migrate (1) +and +.BR lfs-setstripe (1) +for a complete list of options. +.PP +To maintain backward compatibility, the \fI-n \fRoption is used by the +script to indicate a dry-run (no modifications made), and is not passed to +.B lfs migrate +as the non-block option. To specify non-block, use the long option +.BR --non-block . .PP The current file allocation policies on MDS dictate where the new files are placed, taking into account whether specific OSTs have been disabled @@ -57,63 +70,123 @@ directory (potentially changing the stripe count, stripe size, OST pool, or OST index of a new file). .SH OPTIONS .TP -.B \\-c -Restripe file using the specified stripe count. This option may not be -specified at the same time as the -R option. +.B \\--dry-run|-n +Only print the names of files to be migrated. .TP -.B \\-h -Display help information. +.B \\-D +Do not use direct I/O to copy file contents. .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. +.B \\-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 \fB-c \fRor \\-R \fRoptions. +.TP +.B \\--stripe-count|-c \fI +Restripe file using the specified \fIstripe_count\fR. This option may not be +specified at the same time as the \fB-A \fRor \fB-R \fRoptions. +.TP +.B \\-C \fI +When \fB-A \fRis set, limit the migrated file to use on each OST at most +1/\fIcap \fRof 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. +.TP +.B \\--help|-h +Display usage message. +.TP +.B \\--no-rsync +Do not fall back to using rsync if +.BR lfs-migrate (1) " fails." +Cannot be used at the same time as \fB--rsync\fR. .TP -.B \\-n -Only print the names of files to be migrated +.B \\--min-free|-M \fI +When \fB-A \fRis set, only consider OSTs with free space greater than the +\fImin_free \fRvalue to be available for migration. The value is specified in +KB. If this option is not set, a default of 256MB is used. .TP -.B \\-q -Run quietly (don't print filenames or status) +.BR \\--pool | -q \fI +Migrate files to specified pool. .TP -.B \\-R +.BR \\--quiet | -q +Run quietly (don't print filenames or status). +.TP +.B \\--rsync +Force rsync to be used instead of +.BR lfs-migrate (1) . +May not be used at the same time as +.BR --no-rsync . +.TP +.B \\--restripe|-R Restripe file using default directory striping instead of keeping striping. -This option may not be specified at the same time as the -c option. +This option may not be specified at the same time as the \fB-A\fR, \fB-c\fR, or +\fB-S \fRoptions. (these options are passed through to +.BR "lfs migrate" , +and are therefore not listed here). .TP -.B \\-s -skip file data comparison after migrate. Default is to compare migrated file +.B \\--skip|-s +Skip file data comparison after migrate. Default is to compare migrated file against original to verify correctness. .TP -.B \\-y -Answer 'y' to usage warning without prompting (for scripts, use with caution). +.B \\--stripe-size|-S +.I +Restripe file using the specified stripe size. This option may not be +specified at the same time as the \fB-R \fRoption. +.TP +.B \\--verbose|-v +Show verbose debug messages. +.TP +.B \\--max-free|-X \fI +When \fB-A \fRis set, \fImax_free \fRis 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. +.TP +.B \\--yes|-y +Answer 'y' to usage warning without prompt (--rsync only, use with caution). +.TP +.B \\-0 +Input file names on stdin are separated by a null character. .SH EXAMPLES To rebalance all files within -.I /testfs/jobs/2011 -(which are known not to be modified by in-use programs): +.IR /testfs/jobs/2011 : .IP lfs_migrate /testfs/jobs/2011 .PP To migrate files within the .I /testfs filesystem on OST0004 (perhaps because it is much more full than other OSTs), -larger than 4GB (because it is more efficient to just migrate large files), -and older than two days (to avoid files that are in use, though this is NOT -a guarantee the files are not being modified, that is workload specific): +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): .IP -lfs find /testfs -obd test-OST0004 -size +4G -mtime +2d | - lfs_migrate -y -.SH KNOWN BUGS -Hard links could be handled correctly in Lustre 2.0 by using -.BR lfs (1) " fid2path" . +.nf +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 +.fi .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. +To use automatic restriping, and limit the object size per OST to 5% of +current free space: +.IP +lfs_migrate -A -C 20 /testfs/jobs/2011 +.SH NOTES +In versions prior to 2.5, +.B lfs_migrate +is +.B 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 +.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. This will result in the +old file becoming an open-unlinked file, and any modifications to that file +will be lost. .SH AVAILABILITY .B lfs_migrate -is part of the -.BR Lustre (7) +is part of the +.BR Lustre (7) filesystem package. Added in the 1.8.4 release. .SH SEE ALSO .BR lfs (1)