lustre/doc/lfs_migrate.1

   1 .TH lfs_migrate 1 "Dec 19, 2017" Lustre "utilities"
   2 .SH NAME
   3 .B lfs_migrate
   4 \- simple tool to migrate files between Lustre OSTs
   5 .SH SYNOPSIS
   6 .B lfs_migrate
   7 .RB [ --dry-run ]
   8 .RB [ -D ]
   9 .RB [ -h ]
  10 .RB [ --no-rsync | --rsync ]
  11 .RB [ -q ]
  12 .RB [ -R ]
  13 .RB [ -s ]
  14 .RB [ -v ]
  15 .RB [ -y ]
  16 .RB [ -0 ]
  17 .RI [ FILE | DIR ]...
  18 .br
  19 .SH DESCRIPTION
  20 .B lfs_migrate
  21 is a simple tool to assist migration of files between Lustre OSTs.  It
  22 is simply copying each specified file to a new file, verifying the file
  23 contents have not changed, and then renaming the new file back to the
  24 original filename.  This allows balancing space usage between OSTs, moving
  25 files off OSTs that are starting to show hardware problems (though are still
  26 functional), or OSTs that will be removed from the filesystem.
  27 .PP
  28 Files to be migrated can be specified as command-line arguments.  If a
  29 directory is specified on the command-line then all files within that
  30 directory are migrated.  If no files are specified on the command-line,
  31 then a list of files is read from the standard input, making
  32 .B lfs_migrate
  33 suitable for use with
  34 .BR lfs (1) " find"
  35 to locate files on specific OSTs and/or matching other file attributes.
  36 .PP
  37 Any options and arguments not explicitly recognized by the script are passed
  38 through to the
  39 .B lfs migrate
  40 command, see
  41 .BR lfs-migrate (1).
  42 To maintain backward compatibility, the \fI-n \fRoption is used by the script
  43 for a dry-run, and is not passed to
  44 .B lfs migrate
  45 as the non-block option.  To specify non-block, use the long option
  46 .IR --non-block .
  47 .PP
  48 The current file allocation policies on MDS dictate where the new files
  49 are placed, taking into account whether specific OSTs have been disabled
  50 on the MDS via
  51 .BR lctl (8)
  52 (preventing new files from being allocated there), whether
  53 some OSTs are overly full (reducing the number of files placed on those
  54 OSTs), or if there is a specific default file striping for the target
  55 directory (potentially changing the stripe count, stripe size, OST pool,
  56 or OST index of a new file).
  57 .SH OPTIONS
  58 .TP
  59 .B \\--dry-run
  60 Only print the names of files to be migrated.
  61 .TP
  62 .B \\-D
  63 Do not use direct I/O to copy file contents.
  64 .TP
  65 .B \\-h
  66 Display help information.
  67 .TP
  68 .B \\--no-rsync
  69 Do not fall back to using rsync if
  70 .BR lfs (1) " migrate" " fails."
  71 Cannot be used at the same time as \fI--rsync\fR.
  72 .TP
  73 .B \\-q
  74 Run quietly (don't print filenames or status).
  75 .TP
  76 .B \\--rsync
  77 Force rsync to be used instead of
  78 .BR lfs (1) " migrate" .
  79 May not be used at the same time as \fI--no-rsync\fR.
  80 .TP
  81 .B \\-R
  82 Restripe file using default directory striping instead of keeping striping.
  83 This option may not be specified at the same time as the -c or -S options
  84 (these options are passed through to
  85 .BR "lfs migrate" ,
  86 and are therefore not listed here).
  87 .TP
  88 .B \\-s
  89 Skip file data comparison after migrate.  Default is to compare migrated file
  90 against original to verify correctness.
  91 .TP
  92 .B \\-v
  93 Show verbose debug messages.
  94 .TP
  95 .B \\-y
  96 Answer 'y' to usage warning without prompting (for scripts, use with caution).
  97 .TP
  98 .B \\-0
  99 Input file names on stdin are separated by a null character.
 100 .SH EXAMPLES
 101 To rebalance all files within
 102 .I /testfs/jobs/2011
 103 (which are known not to be modified by in-use programs):
 104 .IP
 105 lfs_migrate /testfs/jobs/2011
 106 .PP
 107 To migrate files within the
 108 .I /testfs
 109 filesystem on OST0004 (perhaps because it is much more full than other OSTs),
 110 larger than 4GB (because it is more efficient to just migrate large files),
 111 and older than two days (to avoid files that are in use, though this is NOT
 112 a guarantee the files are not being modified, that is workload specific):
 113 .IP
 114 lfs find /testfs -obd test-OST0004 -size +4G -mtime +2d |
 115     lfs_migrate -y
 116 .SH NOTES
 117 In versions prior to 2.5,
 118 .B lfs_migrate
 119 is
 120 .B not
 121 closely integrated with the MDS, and cannot determine whether a file
 122 is currently open and/or in-use by other applications or nodes.  That makes
 123 it
 124 .B
 125 UNSAFE
 126 for use on files that might be modified by other applications, since the
 127 migrated file is only a copy of the current file. This will result in the
 128 old file becoming an open-unlinked file, and any modifications to that file
 129 will be lost.
 130 .SH KNOWN BUGS
 131 Eventually, this functionality will be integrated into
 132 .BR lfs (1)
 133 itself and will integrate with the MDS layout locking to make it safe
 134 in the presence of opened files and ongoing file IO.
 135 .SH AVAILABILITY
 136 .B lfs_migrate
 137 is part of the
 138 .BR Lustre (7)
 139 filesystem package.  Added in the 1.8.4 release.
 140 .SH SEE ALSO
 141 .BR lfs (1)