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