lustre/doc/lfs-migrate.1

   1 .TH LFS-MIGRATE 1 2021-11-08 "Lustre" "Lustre Utilities"
   2 .SH NAME
   3 lfs migrate \- migrate files or directories between MDTs or OSTs.
   4 .SH SYNOPSIS
   5 .B lfs migrate
   6 .RB [ -h "] [" -v ]
   7 .RI [ SETSTRIPE_OPTIONS " ... ]"
   8 .IR FILE " ..."
   9 .br
  10 .B lfs migrate -m \fISTART_MDT_INDEX
  11 .RB [ -cdHv ]
  12 .I DIRECTORY
  13 .br
  14 .SH DESCRIPTION
  15 Migrate OST objects between OSTs for the specified
  16 .IR FILE ,
  17 or recursively migrate
  18 .I DIRECTORY
  19 and all inodes/directories therein between MDTs.
  20 .SH OST MIGRATE OPTIONS
  21 .P
  22 The
  23 .B lfs migrate
  24 command can be used for moving files from one (or more) OSTs to other
  25 OSTs (e.g. for space balancing between OSTs, or to evacuate an OST for
  26 hardware reasons), to change the stripe count or other layout parameters
  27 of a file (e.g. to increase the bandwidth of a file by striping it over
  28 multiple OSTs), or to move the file between different classes of storage
  29 (e.g. SSD vs. HDD OSTs, or local vs. remote OSTs in different pools).
  30 .P
  31 In OST object migration mode, the command supports the same
  32 .I SETSTRIPE_OPTIONS
  33 listed in
  34 .BR lfs-setstripe (1)
  35 to specify the layout of the target file.  The migrate command differs from
  36 .B lfs setstripe
  37 in that
  38 .B lfs migrate
  39 will copy the data from the existing file(s) using the new layout parameters
  40 to the new OST(s). In contrast,
  41 .B lfs setstripe
  42 is used for creating new (empty) files with the specified layout.
  43 For OST object migration, there additional options available:
  44 .TP
  45 .BR -b , --block
  46 Block access to the file by other applications during data migration
  47 (default).  This prevents other processes from accessing the file during
  48 migration, which prevents data data writes to the old file objects from
  49 being lost.  This should be used if an OST needs to be completely emptied
  50 prior to its removal, to ensure all requested files are migrated off the
  51 OST.
  52 .TP
  53 .BR -h , --help
  54 Print usage message.
  55 .TP
  56 .BR -n , --non-block
  57 Abort migration if concurrent file access is detected.  This can be
  58 used with OST space balancing migration to avoid interfering with file
  59 access by applications if there is not a requirement to migrate any
  60 particular file to the new layout.
  61 .TP
  62 .BR -D , --non-direct
  63 Do
  64 .B not
  65 use
  66 .B O_DIRECT
  67 read and write operations when migrating a file.  The
  68 .B O_DIRECT
  69 option avoids data copy from kernel buffers into userspace, which can
  70 impose CPU and memory overhead on the copy operation, but makes read and
  71 write operations synchronous.  Using the
  72 .B --non-direct
  73 option uses buffered read/write operations, which may improve migration
  74 speed at the cost of more CPU and memory overhead.
  75 .TP
  76 .BR -v , --verbose
  77 Print each filename as it is migrated.
  78 .P
  79 NOTE:
  80 .B lfs migrate
  81 has a complementary
  82 .B lfs_migrate
  83 script which is used to provide extra functionality when migrating file
  84 data between OSTs and has a separate man page.  See
  85 .BR lfs_migrate (1)
  86 for details.
  87 .SH MDT MIGRATE OPTIONS
  88 .TP
  89 .BR -m , --mdt-index=\fIMDT_INDEX [, \fIMDT_INDEX ,...]
  90 The specified
  91 .I DIRECTORY
  92 .B and all subdirectories and inodes
  93 will be migrated to the MDT with the specified
  94 .IR MDT_INDEX .
  95 This is useful if new MDTs have been added to a filesystem and existing user or
  96 project directories should be migrated off old MDTs to balance the space usage
  97 and future metadata workload. If
  98 .I MDT_INDEX
  99 is -1, the MDT index will be balanced by free space and inodes among
 100 available MDTs.  If multiple
 101 .I MDT_INDEX
 102 values are specified in a comma-seperated list, then all
 103 subdirectories will be
 104 .B striped
 105 across all of the specified MDT indices as if an equivalent
 106 .BI -c N
 107 option were given.
 108 .TP
 109 .BR -c , --mdt-count=\fICOUNT\fR
 110 All directories and subdirectories in the tree will be striped across
 111 .I COUNT
 112 MDTs, always using
 113 .I MDT_INDEX
 114 as the primary MDT for the directory.  If
 115 .I MDT_INDEX is
 116 .B -1
 117 then
 118 .I COUNT
 119 directory stripes will be chosen from MDTs proportional to the amount
 120 of free inodes and space on each MDT.  If multiple
 121 .I MDT_INDEX
 122 values are specified in a comma-separated list, then the number of specified
 123 .I MDT_INDEX
 124 values must match
 125 .IR COUNT .
 126 .TP
 127 .BR -d , --directory
 128 Only migrate the specified \fIDIRECTORY\fR and the non-directory inodes that are
 129 directly located within it.
 130 Similar to '\fBls -d\fR' and '\fBlfs getstripe -d\fR'.
 131 .TP
 132 .BR -H , --mdt-hash=\fIHASH_TYPE\fR
 133 Use
 134 .I HASH_TYPE
 135 for the new directory layout.
 136 .RS 1.2i
 137 .TP
 138 .B all_char (type 1)
 139 Sum of ASCII characters modulo number of MDTs. This
 140 provides weak hashing of the filename, and is suitable
 141 for only testing or when the input is known to have
 142 perfectly uniform distribution (e.g. sequential numbers).
 143 .TP
 144 .B fnv_1a_64 (type 2)
 145 Fowler-Noll-Vo (FNV-1a) hash algorithm.  This provides
 146 reasonably uniform, but not cryptographically strong,
 147 hashing of the filename. (default)
 148 .TP
 149 .B crush (type 3)
 150 CRUSH hash algorithm.  This is a consistent hash
 151 algorithm, so minimum sub files need to relocate
 152 during directory restripe.
 153 .RE
 154 .P
 155 .TP
 156 .B NOTE
 157 Only the root user can migrate directories.  Files that have been archived by
 158 HSM or are currently opened will fail to migrate, user can run the same migrate
 159 command again to finish migration when files are ready.  Both inode and
 160 directory entry will be migrated.  During migration directory and sub files can
 161 be accessed like normal ones, but the migration itself cannot be interrupted.
 162 .TP
 163 .B NOTE
 164 It is not currently possible to migrate files with an
 165 .B mdt
 166 component (Data-on-MDT, DoM).  If it is necessary to migrate such files off
 167 a particular MDT, they must first be migrated to have a non-DoM file layout
 168 and then the inodes migrated separately.  See
 169 .B EXAMPLES
 170 for details on how to migrate DoM files between MDTs.
 171 .TP
 172 .B WARNING
 173 Each migrated file or directory will have a new FID, and hence a new inode
 174 number.  As a consequence, files archived by Lustre HSM that depend on
 175 the FID as the identifier in the HSM archive cannot currently be migrated.
 176 Having a new inode number may also cause backup tools to consider the
 177 migrated file(s) to be a new, and cause them to be backed up again.
 178 .P
 179 .SH EXAMPLES
 180 .TP
 181 .B $ lfs migrate -c 2 /mnt/lustre/file1
 182 This migrates the data in
 183 .B file1
 184 into a new layout with 2 stripes.
 185 .TP
 186 .B $ lfs migrate -E 256M -c 1 -E 16G -c 4 -E eof -c 40 /mnt/lustre/file2
 187 .br
 188 This migrates the data in
 189 .B file2
 190 into a three component composite layout (number of stripes depends on
 191 file size).
 192 .TP
 193 .B # lfs migrate -m 0,2 testremote
 194 .br
 195 Recursively move the subdirectories and inodes contained in directory
 196 .B remotedir
 197 from its current MDT to MDT0000 and MDT0002.  The
 198 .B testremote
 199 directory and all of its subdirectories will be striped across both MDTs.
 200 .TP
 201 .B $ lfs migrate -m 0,2 -d ./testremote
 202 Move ./testremote and the first level of sub files from their current MDT
 203 to the MDT with index 0 and 2. Different from above case, the layout of
 204 subdirectories under ./testremote won't be changed.
 205 .TP
 206 .B # lfs setstripe -E 256M -c 1 -E 16G -c 4 -E eof -c 40 topdir
 207 Set a default PFL layout (without any DoM component) on the directory
 208 .BR topdir ,
 209 .TP
 210 .B # lfs find dir -type f -L mdt -0 | xargs -0 lfs migrate --copy topdir
 211 then find and migrate all regular files that have an
 212 .B mdt
 213 component to copy the default layout from the specified
 214 .BR topdir ,
 215 .TP
 216 .B # lfs migrate -m 2 topdir
 217 .br
 218 and finally migrate the directory
 219 .B topdir
 220 and all files and subdirectories in that tree to MDT0002.  This allows
 221 migrating files with DoM components off an MDT.
 222 .SH AUTHOR
 223 The lfs command is part of the Lustre filesystem.
 224 .SH SEE ALSO
 225 .BR lfs (1),
 226 .BR lfs-setstripe (1),
 227 .BR lfs-setdirstripe (1),
 228 .BR lfs-getdirstripe (1),
 229 .BR lfs-mkdir (1),
 230 .BR lfs_migrate (1),
 231 .BR lctl (8),