lustre/doc/lfs_migrate.1

   1 .TH lfs_migrate 1 "Dec 19, 2017" Lustre "utilities"
   2 .SH NAME
   3 .B lfs_migrate
   4 \- migrate files between Lustre OSTs
   5 .SH SYNOPSIS
   6 .B lfs_migrate
   7 .RB [ --dry-run ]
   8 .RB [ --help|-h ]
   9 .RB [ --no-rsync | --rsync ]
  10 .RB [ --pool | -p \fI<pool> \fR]
  11 .RB [ --quiet|-q ]
  12 .RB [ --restripe|-R ]
  13 .RB [ --skip|-s ]
  14 .RB [ --verbose|-v ]
  15 .RB [ --yes|-y ]
  16 .RB [ -D ]
  17 .RB [ -A [ -C \fI<cap> \fR] [ -M \fI<min_free> \fR] [ -X \fI<max_free> \fR]]
  18 .RB [ --stripe-count|-c \fI<stripe_count> \fR]
  19 .RB [ --stripe-size|-S \fI<stripe_size> \fR]
  20 .RB [ -0 ]
  21 .RI [ FILE | DIR ] ...
  22 .br
  23 .SH DESCRIPTION
  24 .B lfs_migrate
  25 is a tool to assist migration of files between Lustre OSTs, possibly also
  26 restriping the files as it goes. It copies each specified file to a new file,
  27 verifies the file contents have not changed, and then replaces the original
  28 filename with the new file (either atomically via
  29 .BR lfs-migrate (1)
  30 on Lustre 2.5 and later, or
  31 .BR mv (1)
  32 on older versions of Lustre). This allows balancing space usage between OSTs,
  33 moving files off OSTs that are starting to show hardware problems but are still
  34 functional, or OSTs that will be removed from the filesystem.
  35 .PP
  36 Files to be migrated can be specified as command-line arguments.  If a
  37 directory is specified on the command-line then all files within that
  38 directory are migrated.  If no files are specified on the command-line,
  39 then a list of files is read from the standard input, making
  40 .B lfs_migrate
  41 suitable for use with
  42 .BR lfs-find (1)
  43 to locate files on specific OSTs and/or matching other file attributes,
  44 or any other tools that generate a list of files.
  45 .PP
  46 Any options and arguments not explicitly recognized by
  47 .B lfs_migrate
  48 are passed through to the underlying
  49 .B lfs migrate
  50 command, see
  51 .BR lfs-migrate (1)
  52 and
  53 .BR lfs-setstripe (1)
  54 for a complete list of options.
  55 .PP
  56 To maintain backward compatibility, the \fI-n \fRoption is used by the
  57 script to indicate a dry-run (no modifications made), and is not passed to
  58 .B lfs migrate
  59 as the non-block option.  To specify non-block, use the long option
  60 .BR --non-block .
  61 .PP
  62 The current file allocation policies on MDS dictate where the new files
  63 are placed, taking into account whether specific OSTs have been disabled
  64 on the MDS via
  65 .BR lctl (8)
  66 (preventing new files from being allocated there), whether
  67 some OSTs are overly full (reducing the number of files placed on those
  68 OSTs), or if there is a specific default file striping for the target
  69 directory (potentially changing the stripe count, stripe size, OST pool,
  70 or OST index of a new file).
  71 .SH OPTIONS
  72 .TP
  73 .B \\--dry-run|-n
  74 Only print the names of files to be migrated.
  75 .TP
  76 .B \\-D
  77 Do not use direct I/O to copy file contents.
  78 .TP
  79 .B \\-A
  80 Automatically determine the stripe count for the file, using the algorithm
  81 count = sqrt(filesize_in_GB) + 1.  This option may not be specified at the
  82 same time as the \fB-c \fRor \\-R \fRoptions.
  83 .TP
  84 .B \\--stripe-count|-c \fI<stripe_count>
  85 Restripe file using the specified \fIstripe_count\fR. This option may not be
  86 specified at the same time as the \fB-A \fRor \fB-R \fRoptions.
  87 .TP
  88 .B \\-C \fI<cap>
  89 When \fB-A \fRis set, limit the migrated file to use on each OST at most
  90 1/\fIcap \fRof the available space of the smallest OST.  If this option is not
  91 set, a default value of 100 is used, limiting the object size to 1% of available
  92 space.
  93 .TP
  94 .B \\--help|-h
  95 Display help information.
  96 .TP
  97 .B \\--no-rsync
  98 Do not fall back to using rsync if
  99 .BR lfs-migrate (1) " fails."
 100 Cannot be used at the same time as \fB--rsync\fR.
 101 .B \\--min-free|-M \fI<min_free>
 102 When \fB-A \fRis set, only consider OSTs with free space greater than the
 103 \fImin_free \fRvalue to be available for migration.  The value is specified in
 104 KB. If this option is not set, a default of 256MB is used.
 105 .TP
 106 .BR \\--pool | -q \fI<pool>
 107 Migrate files to specified pool.
 108 .TP
 109 .BR \\--quiet | -q
 110 Run quietly (don't print filenames or status).
 111 .TP
 112 .B \\--rsync
 113 Force rsync to be used instead of
 114 .BR lfs-migrate (1) .
 115 May not be used at the same time as
 116 .BR --no-rsync .
 117 .TP
 118 .B \\--restripe|-R
 119 Restripe file using default directory striping instead of keeping striping.
 120 This option may not be specified at the same time as the \fB-A\fR, \fB-c\fR, or
 121 \fB-S \fRoptions.  (these options are passed through to
 122 .BR "lfs migrate" ,
 123 and are therefore not listed here).
 124 .TP
 125 .B \\--skip|-s
 126 Skip file data comparison after migrate.  Default is to compare migrated file
 127 against original to verify correctness.
 128 .TP
 129 .B \\--verbose|-v
 130 Show verbose debug messages.
 131 .B \\--max-free|-X \fI<max_free>
 132 When \fB-A \fRis set, \fImax_free \fRis the maximum amount of free space that
 133 can be considered available for the migration of the file on each OST.  The
 134 value is specified in KB.  This option is useful for testing, by simulating
 135 OSTs that are nearly full.
 136 .TP
 137 .B \\--yes|-y
 138 Answer 'y' to usage warning without prompting (for scripts; use with caution).
 139 .SH EXAMPLES
 140 To rebalance all files within
 141 .I /testfs/jobs/2011
 142 .B \\--stripe-size|-S
 143 .I <stripe_size>
 144 Restripe file using the specified stripe size. This option may not be
 145 specified at the same time as the \fB-R \fRoption.
 146 .TP
 147 .B \\--yes|-y
 148 Answer 'y' to usage warning without prompting (for scripts, use with caution).
 149 .TP
 150 .B \\-0
 151 Input file names on stdin are separated by a null character.
 152 .SH EXAMPLES
 153 To rebalance all files within
 154 .I /testfs/jobs/2011
 155 (which are known not to be modified by in-use programs):
 156 .IP
 157 lfs_migrate /testfs/jobs/2011
 158 .PP
 159 To migrate files within the
 160 .I /testfs
 161 filesystem on OST0004 (perhaps because it is much more full than other OSTs),
 162 larger than 4GB (because it is more efficient to just migrate large files),
 163 and older than two days (to avoid files that are in use, though this is NOT
 164 a guarantee the files are not being modified, that is workload specific) after
 165 disabling file creation on testfs-OST0004 (this is needed on all MDS nodes):
 166 .IP
 167 .nf
 168 mds# lctl set_param osp.testfs-OST0004*.max_create_count=0
 169 client# lfs find /testfs -obd testfs-OST0004 -size +4G -mtime +2d | lfs_migrate -y
 170 mds# lctl set_param osp.testfs-OST0004*.max_create_count=20000
 171 .fi
 172 .PP
 173 To use automatic striping, and limit the object size per OST to 5% of current
 174 free space:
 175 .IP
 176 lfs_migrate -A -C 20 /testfs/jobs/2011
 177 .SH NOTES
 178 In versions prior to 2.5,
 179 .B lfs_migrate
 180 is
 181 .B not
 182 closely integrated with the MDS, and cannot determine whether a file
 183 is currently open and/or in-use by other applications or nodes.  That makes
 184 it
 185 .B UNSAFE
 186 for use on files that might be modified by other applications, since the
 187 migrated file is only a copy of the current file. This will result in the
 188 old file becoming an open-unlinked file, and any modifications to that file
 189 will be lost.
 190 .SH AVAILABILITY
 191 .B lfs_migrate
 192 is part of the
 193 .BR Lustre (7)
 194 filesystem package.  Added in the 1.8.4 release.
 195 .SH SEE ALSO
 196 .BR lfs (1)