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