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 [ --quiet|-q ]
  11 .RB [ --restripe|-R ]
  12 .RB [ --skip|-s ]
  13 .RB [ --verbose|-v ]
  14 .RB [ --yes|-y ]
  15 .RB [ -0 ]
  16 .RI [ FILE | DIR ]...
  17 .br
  18 .SH DESCRIPTION
  19 .B lfs_migrate
  20 is a tool to assist migration of files between Lustre OSTs, possibly also
  21 restriping the files as it goes. It copies each specified file to a new file,
  22 verifies the file contents have not changed, and then replaces the original
  23 filename with the new file (either atomically via
  24 .BR lfs-migrate (1)
  25 on Lustre 2.5 and later, or
  26 .BR mv (1)
  27 on older versions of Lustre). This allows balancing space usage between OSTs,
  28 moving files off OSTs that are starting to show hardware problems but are still
  29 functional, or OSTs that will be removed from the filesystem.
  30 .PP
  31 Files to be migrated can be specified as command-line arguments.  If a
  32 directory is specified on the command-line then all files within that
  33 directory are migrated.  If no files are specified on the command-line,
  34 then a list of files is read from the standard input, making
  35 .B lfs_migrate
  36 suitable for use with
  37 .BR lfs-find (1)
  38 to locate files on specific OSTs and/or matching other file attributes,
  39 or any other tools that generate a list of files.
  40 .PP
  41 Any options and arguments not explicitly recognized by
  42 .B lfs_migrate
  43 are passed through to the underlying
  44 .B lfs migrate
  45 command, see
  46 .BR lfs-migrate (1)
  47 and
  48 .BR lfs-setstripe (1)
  49 for a complete list of options.
  50 .PP
  51 To maintain backward compatibility, the \fI-n \fRoption is used by the
  52 script to indicate a dry-run (no modifications made), and is not passed to
  53 .B lfs migrate
  54 as the non-block option.  To specify non-block, use the long option
  55 .IR --non-block .
  56 .PP
  57 The current file allocation policies on MDS dictate where the new files
  58 are placed, taking into account whether specific OSTs have been disabled
  59 on the MDS via
  60 .BR lctl (8)
  61 (preventing new files from being allocated there), whether
  62 some OSTs are overly full (reducing the number of files placed on those
  63 OSTs), or if there is a specific default file striping for the target
  64 directory (potentially changing the stripe count, stripe size, OST pool,
  65 or OST index of a new file).
  66 .SH OPTIONS
  67 .TP
  68 .B \\--dry-run
  69 Only print the names of files to be migrated.
  70 .TP
  71 .B \\--help|-h
  72 Display help information.
  73 .TP
  74 .B \\--no-rsync
  75 Do not fall back to using rsync if
  76 .BR lfs (1) " migrate" " fails."
  77 Cannot be used at the same time as \fI--rsync\fR.
  78 .TP
  79 .B \\--quiet|-q
  80 Run quietly (don't print filenames or status).
  81 .TP
  82 .B \\--rsync
  83 Force rsync to be used instead of
  84 .BR lfs (1) " migrate" .
  85 May not be used at the same time as \fI--no-rsync\fR.
  86 .TP
  87 .B \\--restripe|-R
  88 Restripe file using default directory striping instead of keeping striping.
  89 This option may not be specified at the same time as the -c or -S options
  90 (these options are passed through to
  91 .BR "lfs migrate" ,
  92 and are therefore not listed here).
  93 .TP
  94 .B \\--skip|-s
  95 Skip file data comparison after migrate.  Default is to compare migrated file
  96 against original to verify correctness.
  97 .TP
  98 .B \\--verbose|-v
  99 Show verbose debug messages.
 100 .TP
 101 .B \\--yes|-y
 102 Answer 'y' to usage warning without prompting (for scripts, use with caution).
 103 .TP
 104 .B \\-0
 105 Input file names on stdin are separated by a null character.
 106 .SH EXAMPLES
 107 To rebalance all files within
 108 .I /testfs/jobs/2011
 109 (which are known not to be modified by in-use programs):
 110 .IP
 111 lfs_migrate /testfs/jobs/2011
 112 .PP
 113 To migrate files within the
 114 .I /testfs
 115 filesystem on OST0004 (perhaps because it is much more full than other OSTs),
 116 larger than 4GB (because it is more efficient to just migrate large files),
 117 and older than two days (to avoid files that are in use, though this is NOT
 118 a guarantee the files are not being modified, that is workload specific) after
 119 disabling file creation on testfs-OST0004 (this is needed on all MDS nodes):
 120 .IP
 121 mds# lctl set_param osp.testfs-OST0004*.max_create_count=0
 122 client# lfs find /testfs -obd testfs-OST0004 -size +4G -mtime +2d | lfs_migrate -y
 123 mds# lctl set_param osp.testfs-OST0004*.max_create_count=20000
 124 .SH NOTES
 125 In versions prior to 2.5,
 126 .B lfs_migrate
 127 is
 128 .B not
 129 closely integrated with the MDS, and cannot determine whether a file
 130 is currently open and/or in-use by other applications or nodes.  That makes
 131 it
 132 .B UNSAFE
 133 for use on files that might be modified by other applications, since the
 134 migrated file is only a copy of the current file. This will result in the
 135 old file becoming an open-unlinked file, and any modifications to that file
 136 will be lost.
 137 .SH AVAILABILITY
 138 .B lfs_migrate
 139 is part of the
 140 .BR Lustre (7)
 141 filesystem package.  Added in the 1.8.4 release.
 142 .SH SEE ALSO
 143 .BR lfs (1)