lustre/doc/lfs_migrate.1

   1 .TH lfs_migrate 1 "Jul 21, 2010" Lustre "utilities"
   2 .SH NAME
   3 .B lfs_migrate
   4 \- simple tool to migrate files between Lustre OSTs
   5 .SH SYNOPSIS
   6 .B lfs_migrate
   7 .RB [ -c <stripe_count> ]
   8 .RB [ -h ]
   9 .RB [ -l ]
  10 .RB [ -n ]
  11 .RB [ -q ]
  12 .RB [ -R ]
  13 .RB [ -s ]
  14 .RB [ -y ]
  15 .RI [ file | "directory ..." ]
  16 .br
  17 .SH DESCRIPTION
  18 .B lfs_migrate
  19 is a simple tool to assist migration of files between Lustre OSTs.  It
  20 is simply copying each specified file to a new file, verifying the file
  21 contents have not changed, and then renaming the new file back to the
  22 original filename.  This allows balancing space usage between OSTs, moving
  23 files off OSTs that are starting to show hardware problems (though are still
  24 functional), or OSTs that will be removed from the filesystem.
  25 .PP
  26 Because
  27 .B lfs_migrate
  28 is
  29 .B not
  30 yet closely integrated with the MDS, it cannot determine whether a file
  31 is currently open and/or in-use by other applications or nodes.  That makes
  32 it
  33 .B
  34 UNSAFE
  35 for use on files that might be modified by other applications, since the
  36 migrated file is only a copy of the current file, and this will result in
  37 the old file becoming an open-unlinked file and any modifications to that
  38 file will be lost.
  39 .PP
  40 Files to be migrated can be specified as command-line arguments.  If a
  41 directory is specified on the command-line then all files within that
  42 directory are migrated.  If no files are specified on the command-line,
  43 then a list of files is read from the standard input, making
  44 .B lfs_migrate
  45 suitable for use with
  46 .BR lfs (1) " find"
  47 to locate files on specific OSTs and/or matching other file attributes.
  48 .PP
  49 The current file allocation policies on MDS dictate where the new files
  50 are placed, taking into account whether specific OSTs have been disabled
  51 on the MDS via
  52 .BR lctl (8)
  53 (preventing new files from being allocated there), whether
  54 some OSTs are overly full (reducing the number of files placed on those
  55 OSTs), or if there is a specific default file striping for the target
  56 directory (potentially changing the stripe count, stripe size, OST pool,
  57 or OST index of a new file).
  58 .SH OPTIONS
  59 .TP
  60 .B \\-c <stripe_count>
  61 Restripe file using the specified stripe count. This option may not be
  62 specified at the same time as the -R option.
  63 .TP
  64 .B \\-h
  65 Display help information.
  66 .TP
  67 .B \\-l
  68 Migrate files with hard links (skip by default).  Files with multiple
  69 hard links will be split into multiple separate files by
  70 .B lfs_migrate
  71 so they are skipped by default to avoid breaking the hard links.
  72 .TP
  73 .B \\-n
  74 Only print the names of files to be migrated
  75 .TP
  76 .B \\-q
  77 Run quietly (don't print filenames or status)
  78 .TP
  79 .B \\-R
  80 Restripe file using default directory striping instead of keeping striping.
  81 This option may not be specified at the same time as the -c option.
  82 .TP
  83 .B \\-s
  84 skip file data comparison after migrate.  Default is to compare migrated file
  85 against original to verify correctness.
  86 .TP
  87 .B \\-y
  88 Answer 'y' to usage warning without prompting (for scripts, use with caution).
  89 .SH EXAMPLES
  90 To rebalance all files within
  91 .I /testfs/jobs/2011
  92 (which are known not to be modified by in-use programs):
  93 .IP
  94 lfs_migrate /testfs/jobs/2011
  95 .PP
  96 To migrate files within the
  97 .I /testfs
  98 filesystem on OST0004 (perhaps because it is much more full than other OSTs),
  99 larger than 4GB (because it is more efficient to just migrate large files),
 100 and older than two days (to avoid files that are in use, though this is NOT
 101 a guarantee the files are not being modified, that is workload specific):
 102 .IP
 103 lfs find /testfs -obd test-OST0004 -size +4G -mtime +2d |
 104     lfs_migrate -y
 105 .SH KNOWN BUGS
 106 Hard links could be handled correctly in Lustre 2.0 by using
 107 .BR lfs (1) " fid2path" .
 108 .PP
 109 Eventually, this functionality will be integrated into
 110 .BR lfs (1)
 111 itself and will integrate with the MDS layout locking to make it safe
 112 in the presence of opened files and ongoing file IO.
 113 .SH AVAILABILITY
 114 .B lfs_migrate
 115 is part of the
 116 .BR Lustre (7)
 117 filesystem package.  Added in the 1.8.4 release.
 118 .SH SEE ALSO
 119 .BR lfs (1)