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 mdt_idx
   9 .RB [ -v | --verbose ]
  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 .RB -m , --mdt-index
  79 Causes the file metadata (inode) to be migrated to the MDT with index
  80 .IR mdt_idx .
  81 This is useful if new MDTs have been added to a filesystem and existing
  82 user or project directories should be migrated off old MDTs to balance
  83 the space usage and future metadata workload.
  84 .P
  85 Migration of striped directories or individual files between MDTs is not
  86 currently supported. Only the root user can migrate directories.  Files that
  87 have been archived by HSM or are currently open are skipped by MDT inode
  88 migration. Access to files within the directory is blocked until migration is
  89 complete.
  90 .TP
  91 \fIWARNING\fR
  92 A migrated file or directory will have a new FID, and hence a new inode
  93 number.  As a consequence, files archived by Lustre HSM that depend on
  94 the FID as the identifier in the HSM archive cannot currently be migrated.
  95 Having a new inode number may also cause backup tools to consider the
  96 migrated file(s) to be a new, and cause them to be backed up again.
  97 .SH EXAMPLES
  98 .TP
  99 .B $ lfs migrate -c 2 /mnt/lustre/file1
 100 This migrates the file into a new layout with 2 stripes.
 101 .TP
 102 .B $ lfs migrate -E 64M -c 1 -E 256M -c 4 -E -1 -c -1 /mnt/lustre/file1
 103 This migrates the file into a three component composite layout.
 104 .TP
 105 .B $ lfs migrate -m 0 ./testremote
 106 Move the inodes contained in directory ./testremote from their current
 107 MDT to the MDT with index 0.
 108 .SH AUTHOR
 109 The lfs command is part of the Lustre filesystem.
 110 .SH SEE ALSO
 111 .BR lfs (1),
 112 .BR lfs-setstripe (1),
 113 .BR lfs-setdirstripe (1),
 114 .BR lfs-getdirstripe (1),
 115 .BR lfs-mkdir (1),
 116 .BR lfs_migrate (1),
 117 .BR lctl (8),