lustre/doc/lfs-migrate.1

   1 .TH LFS-MIGRATE 1 2015-12-07 "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 .RI < file "> ..."
   9 .br
  10 .B lfs migrate -m \fIstart_mdt_index
  11 .RB [ -cHv ]
  12 .RI < directory >
  13 .br
  14 .SH DESCRIPTION
  15 Migrate OST objects or MDT inodes between MDTs and OSTs respectively.
  16 .P
  17 The
  18 .B lfs migrate
  19 command can be used for moving files from one (or more) OSTs to other
  20 OSTs (e.g. for space balancing between OSTs, or to evacuate an OST for
  21 hardware reasons), to change the stripe count or other layout parameters
  22 of a file (e.g. to increase the bandwidth of a file by striping it over
  23 multiple OSTs), or to move the file between different classes of storage
  24 (e.g. SSD vs. HDD OSTs, or local vs. remote OSTs in different pools).
  25 .P
  26 In OST object migration mode, the command supports the same
  27 .I SETSTRIPE_OPTIONS
  28 listed in
  29 .BR lfs-setstripe (1)
  30 to specify the layout of the target file.  The migrate command differs
  31 from
  32 .B lfs setstripe
  33 in that
  34 .B lfs migrate
  35 will copy the data from the existing file(s) using the new layout parameters
  36 to the new OST(s). In contrast,
  37 .B lfs setstripe
  38 is used for creating new (empty) files with the specified layout.
  39 .SH OST MIGRATE OPTIONS
  40 For OST object migration, there additional options available:
  41 .TP
  42 .BR -b , --block
  43 Block access to the file by other applications during data migration
  44 (default).  This prevents other processes from accessing the file during
  45 migration, which prevents data data writes to the old file objects from
  46 being lost.  This should be used if an OST needs to be completely emptied
  47 prior to its removal, to ensure all requested files are migrated off the
  48 OST.
  49 .TP
  50 .BR -h , --help
  51 Print usage message.
  52 .TP
  53 .BR -n , --non-block
  54 Abort migration if concurrent file access is detected.  This can be
  55 used with OST space balancing migration to avoid interfering with file
  56 access by applications if there is not a requirement to migrate any
  57 particular file to the new layout.
  58 .TP
  59 .BR -D , --non-direct
  60 Do
  61 .B not
  62 use
  63 .B O_DIRECT
  64 read and write operations when migrating a file.  The
  65 .B O_DIRECT
  66 option avoids data copy from kernel buffers into userspace, which can
  67 impose CPU and memory overhead on the copy operation, but makes read and
  68 write operations synchronous.  Using the
  69 .B --non-direct
  70 option uses buffered read/write operations, which may improve migration
  71 speed at the cost of more CPU and memory overhead.
  72 .TP
  73 .BR -v , --verbose
  74 Print each filename as it is migrated.
  75 .P
  76 NOTE:
  77 .B lfs migrate
  78 has a complementary
  79 .B lfs_migrate
  80 script which is used to provide extra functionality when migrating file
  81 data between OSTs and has a separate man page.  See
  82 .BR lfs_migrate (1)
  83 for details.
  84 .SH MDT MIGRATE OPTIONS
  85 .TP
  86 .BR -m , --mdt-index=\fIstart_mdt_index\fR
  87 Directory will be migrated to MDTs starting with
  88 .I start_mdt_index
  89 , or specific MDTs if multiple MDTs are specified in a comma-seperated list.
  90 This is useful if new MDTs have been added to a filesystem and existing user or
  91 project directories should be migrated off old MDTs to balance the space usage
  92 and future metadata workload. If
  93 .I start_mdt_index
  94 is set to -1, the MDT will be chosen by space and inode usage.
  95 .TP
  96 .BR -c , --mdt-count=\fICOUNT\fR
  97 Directory will be migrated to
  98 .I COUNT
  99 MDTs.
 100 .TP
 101 .BR -H , --mdt-hash=\fIHASH_TYPE\fR
 102 Use
 103 .I HASH_TYPE
 104 for the new layout.
 105 .RS 1.2i
 106 .TP
 107 .B all_char (type 1)
 108 Sum of ASCII characters modulo number of MDTs. This
 109 provides weak hashing of the filename, and is suitable
 110 for only testing or when the input is known to have
 111 perfectly uniform distribution (e.g. sequential numbers).
 112 .TP
 113 .B fnv_1a_64 (type 2)
 114 Fowler-Noll-Vo (FNV-1a) hash algorithm.  This provides
 115 reasonably uniform, but not cryptographically strong,
 116 hashing of the filename. (default)
 117 .TP
 118 .B crush (type 3)
 119 CRUSH hash algorithm.  This is a consistent hash
 120 algorithm, so minimum sub files need to relocate
 121 during directory restripe.
 122 .RE
 123 .P
 124 Only the root user can migrate directories.  Files that have been archived by
 125 HSM or are currently opened will fail to migrate, user can run the same migrate
 126 command again to finish migration when files are ready.  Both inode and
 127 directory entry will be migrated.  During migration directory and sub files can
 128 be accessed like normal ones.
 129 .TP
 130 \fIWARNING\fR
 131 A migrated file or directory will have a new FID, and hence a new inode
 132 number.  As a consequence, files archived by Lustre HSM that depend on
 133 the FID as the identifier in the HSM archive cannot currently be migrated.
 134 Having a new inode number may also cause backup tools to consider the
 135 migrated file(s) to be a new, and cause them to be backed up again.
 136 .P
 137 .SH EXAMPLES
 138 .TP
 139 .B $ lfs migrate -c 2 /mnt/lustre/file1
 140 This migrates the file into a new layout with 2 stripes.
 141 .TP
 142 .B $ lfs migrate -E 64M -c 1 -E 256M -c 4 -E -1 -c -1 /mnt/lustre/file1
 143 This migrates the file into a three component composite layout.
 144 .TP
 145 .B $ lfs migrate -m 0,2 ./testremote
 146 Move the inodes contained in directory ./testremote from their current
 147 MDT to the MDT with index 0 and 2.
 148 .SH AUTHOR
 149 The lfs command is part of the Lustre filesystem.
 150 .SH SEE ALSO
 151 .BR lfs (1),
 152 .BR lfs-setstripe (1),
 153 .BR lfs-setdirstripe (1),
 154 .BR lfs-getdirstripe (1),
 155 .BR lfs-mkdir (1),
 156 .BR lfs_migrate (1),
 157 .BR lctl (8),