Whamcloud - gitweb
LU-930 doc: fix formatting errors in lfs_migrate.1
[fs/lustre-release.git] / lustre / doc / lfs_migrate.1
1 .TH lfs_migrate 1 "Dec 19, 2017" Lustre "utilities"
3 .B lfs_migrate
4 \- migrate files between Lustre OSTs
6 .B lfs_migrate
7 .RB [ "-A " [ -C \fI<cap> \fR] [ -M \fI<min_free> \fR] [ -X \fI<max_free> \fR]]
8 .RB [ --dry-run | -n ]
9 .RB [ --help | -h ]
10 .RB [ --no-rsync | --rsync ]
11 .RB [ --quiet | -q ]
12 .RB [ --restripe | -R ]
13 .RB [ --stripe-count | -c \fI<stripe_count> \fR]
14 .RB [ --stripe-size | -S \fI<stripe_size> \fR]
15 .RB [ --skip | -s ]
16 .RB [ --verbose | -v ]
17 .RB [ --yes | -y ]
18 .RB [ -D ]
19 .RB [ -0 ]
20 .RI [ FILE | DIR ] ...
21 .br
23 .B lfs_migrate
24 is a tool to assist migration of files between Lustre OSTs, possibly also
25 restriping the files as it goes. It copies each specified file to a new file,
26 verifies the file contents have not changed, and then replaces the original
27 filename with the new file (either atomically via
28 .BR lfs-migrate (1)
29 on Lustre 2.5 and later, or
30 .BR mv (1)
31 on older versions of Lustre). This allows balancing space usage between OSTs,
32 moving files off OSTs that are starting to show hardware problems but are still
33 functional, or OSTs that will be removed from the filesystem.
34 .PP
35 Files to be migrated can be specified as command-line arguments.  If a
36 directory is specified on the command-line then all files within that
37 directory are migrated.  If no files are specified on the command-line,
38 then a list of files is read from the standard input, making
39 .B lfs_migrate
40 suitable for use with
41 .BR lfs-find (1)
42 to locate files on specific OSTs and/or matching other file attributes,
43 or any other tools that generate a list of files.
44 .PP
45 Any options and arguments not explicitly recognized by
46 .B lfs_migrate
47 are passed through to the underlying
48 .B lfs migrate
49 command, see
50 .BR lfs-migrate (1)
51 and
52 .BR lfs-setstripe (1)
53 for a complete list of options.
54 .PP
55 To maintain backward compatibility, the \fI-n \fRoption is used by the
56 script to indicate a dry-run (no modifications made), and is not passed to
57 .B lfs migrate
58 as the non-block option.  To specify non-block, use the long option
59 .BR --non-block .
60 .PP
61 The current file allocation policies on MDS dictate where the new files
62 are placed, taking into account whether specific OSTs have been disabled
63 on the MDS via
64 .BR lctl (8)
65 (preventing new files from being allocated there), whether
66 some OSTs are overly full (reducing the number of files placed on those
67 OSTs), or if there is a specific default file striping for the target
68 directory (potentially changing the stripe count, stripe size, OST pool,
69 or OST index of a new file).
71 .TP
72 .B \\--dry-run|-n
73 Only print the names of files to be migrated.
74 .TP
75 .B \\-D
76 Do not use direct I/O to copy file contents.
77 .TP
78 .B \\-A
79 Automatically determine the stripe count for the file, using the algorithm
80 count = sqrt(filesize_in_GB) + 1.  This option may not be specified at the
81 same time as the \fB-c \fRor \\-R \fRoptions.
82 .TP
83 .B \\--stripe-count|-c \fI<stripe_count>
84 Restripe file using the specified \fIstripe_count\fR. This option may not be
85 specified at the same time as the \fB-A \fRor \fB-R \fRoptions.
86 .TP
87 .B \\-C \fI<cap>
88 When \fB-A \fRis set, limit the migrated file to use on each OST at most
89 1/\fIcap \fRof the available space of the smallest OST.  If this option is not
90 set, a default value of 100 is used, limiting the object size to 1% of available
91 space.
92 .TP
93 .B \\--help|-h
94 Display help information.
95 .TP
96 .B \\--no-rsync
97 Do not fall back to using rsync if
98 .BR lfs-migrate (1) " fails."
99 Cannot be used at the same time as \fB--rsync\fR.
100 .TP
101 .B \\--min-free|-M \fI<min_free>
102 When \fB-A \fRis set, only consider OSTs with free space greater than the
103 \fImin_free \fRvalue to be available for migration.  The value is specified in
104 KB. If this option is not set, a default of 256MB is used.
105 .TP
106 .B \\--quiet|-q
107 Run quietly (don't print filenames or status).
108 .TP
109 .B \\--rsync
110 Force rsync to be used instead of
111 .BR lfs-migrate (1) .
112 May not be used at the same time as
113 .BR --no-rsync .
114 .TP
115 .B \\--restripe|-R
116 Restripe file using default directory striping instead of keeping striping.
117 This option may not be specified at the same time as the \fB-A\fR, \fB-c\fR, or
118 \fB-S \fRoptions.  (these options are passed through to
119 .BR "lfs migrate" ,
120 and are therefore not listed here).
121 .TP
122 .B \\--skip|-s
123 Skip file data comparison after migrate.  Default is to compare migrated file
124 against original to verify correctness.
125 .TP
126 .B \\--stripe-size|-S
127 .I <stripe_size>
128 Restripe file using the specified stripe size. This option may not be
129 specified at the same time as the \fB-R \fRoption.
130 .TP
131 .B \\--verbose|-v
132 Show verbose debug messages.
133 .B \\--max-free|-X \fI<max_free>
134 When \fB-A \fRis set, \fImax_free \fRis the maximum amount of free space that
135 can be considered available for the migration of the file on each OST.  The
136 value is specified in KB.  This option is useful for testing, by simulating
137 OSTs that are nearly full.
138 .TP
139 .B \\--yes|-y
140 Answer 'y' to usage warning without prompting (for scripts, use with caution).
141 .TP
142 .B \\-0
143 Input file names on stdin are separated by a null character.
145 To rebalance all files within
146 .I /testfs/jobs/2011
147 (which are known not to be modified by in-use programs):
148 .IP
149 lfs_migrate /testfs/jobs/2011
150 .PP
151 To migrate files within the
152 .I /testfs
153 filesystem on OST0004 (perhaps because it is much more full than other OSTs),
154 larger than 4GB (because it is more efficient to just migrate large files),
155 and older than two days (to avoid files that are in use, though this is NOT
156 a guarantee the files are not being modified, that is workload specific) after
157 disabling file creation on testfs-OST0004 (this is needed on all MDS nodes):
158 .IP
159 .nf
160 mds# lctl set_param osp.testfs-OST0004*.max_create_count=0
161 client# lfs find /testfs -obd testfs-OST0004 -size +4G -mtime +2d | lfs_migrate -y
162 mds# lctl set_param osp.testfs-OST0004*.max_create_count=20000
163 .fi
164 .PP
165 To use automatic striping, and limit the object size per OST to 5% of current
166 free space:
167 .IP
168 lfs_migrate -A -C 20 /testfs/jobs/2011
170 In versions prior to 2.5,
171 .B lfs_migrate
172 is
173 .B not
174 closely integrated with the MDS, and cannot determine whether a file
175 is currently open and/or in-use by other applications or nodes.  That makes
176 it
178 for use on files that might be modified by other applications, since the
179 migrated file is only a copy of the current file. This will result in the
180 old file becoming an open-unlinked file, and any modifications to that file
181 will be lost.
183 .B lfs_migrate
184 is part of the
185 .BR Lustre (7)
186 filesystem package.  Added in the 1.8.4 release.
188 .BR lfs (1)