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